Merge pull request 'updater-ssh' (#28) from updater-ssh into main

Reviewed-on: http://git.factory.uga.edu/UGA-Innovation-Factory/athenix/pulls/28

.github/copilot-instructions.md

@@ -26,8 +26,9 @@ This is a **NixOS system configuration repository** that uses:
 - **`flake.nix`**: Entry point - inputs and outputs only
 - **`inventory.nix`**: Fleet definitions - host configurations
 - **`users.nix`**: User account definitions
-- **`hosts/`**: Host generation logic and hardware types
+- **`variants/`**: Hardware type modules (desktop, laptop, surface, lxc, wsl, etc.)
-- **`sw/`**: Software configurations organized by system type
+- **`glue/`**: Fleet generation logic and common system configuration
+- **`sw/`**: Software configurations by system type
 - **`installer/`**: Build artifact generation (ISO, LXC, etc.)
 - **`templates/`**: Templates for external configurations
 

README.md

@@ -1,156 +1,159 @@
-# UGA Innovation Factory - Athenix
+# Athenix - UGA Innovation Factory NixOS Configuration
 
 [![CI](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions/workflows/ci.yml/badge.svg)](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions)
 
-This repository contains the NixOS configuration for the Innovation Factory's fleet of laptops, desktops, Surface tablets, and containers. It provides a declarative, reproducible system configuration using Nix flakes.
+Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes.
 
-## Documentation
+## Quick Navigation
 
-- **[Quick Start](#quick-start)** - Get started in 5 minutes
+- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Define and configure hosts
-- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Configure hosts and fleet inventory
+- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - All `athenix.*` options reference
-- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - Configuration options reference (`athenix.*`)
+- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User accounts and dotfiles
-- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User account management
+- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External system and user configurations
-- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External configuration modules
+- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs, containers, and artifacts
-- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs and container images
+- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflow and testing
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development and testing workflow
 
-## Quick Start
+## Getting Started
 
 ### For End Users
 
-Update your system to the latest configuration:
+Update your system:
 
 ```bash
 update-system
 ```
 
-This command automatically fetches the latest configuration, rebuilds your system, and uses remote builders on Surface tablets to speed up builds.
+This automatically rebuilds your system with the latest configuration from the repository.
-
-**Note:** If you use external user configurations (personal dotfiles), run:
-```bash
-sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git --impure
-```
 
 ### For Administrators
 
+Make configuration changes:
+
 ```bash
-# 1. Make changes to configuration files
+# Edit inventory
 vim inventory.nix
 
-# 2. Test configuration
+# Validate changes
 nix flake check
 
-# 3. Format code
+# Format code
 nix fmt
 
-# 4. Commit and push
+# Commit and push
-git add .
+git add . && git commit -m "Your message" && git push
-git commit -m "Description of changes"
-git push
 ```
 
-Users can now run `update-system` to get the changes.
+Users automatically get changes when they run `update-system`.
-
-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development workflow.**
 
 ## Repository Structure
 
 ```
-nixos-systems/
+flake.nix                 # Flake entry point (inputs + outputs)
-├── flake.nix           # Flake entry point
+inventory.nix             # Fleet inventory and host definitions
-├── inventory.nix       # Fleet inventory - Define hosts here
+users.nix                 # User account definitions
-├── users.nix           # User accounts - Define users here
+
-├── hosts/              # Host generation logic
+flake.lock                # Locked dependency versions
-│   ├── types/          # Hardware types (desktop, laptop, surface, lxc, wsl, ephemeral)
+
-│   └── ...
+variants/                 # Hardware type modules (exportable as nixosModules)
-├── sw/                 # Software configurations by system type
+├── default.nix           # Auto-exports all variant types
-│   ├── desktop/        # Full desktop environment
+├── nix-desktop.nix       # Desktop workstations
-│   ├── tablet-kiosk/   # Surface kiosk mode
+├── nix-laptop.nix        # Laptop systems
-│   ├── stateless-kiosk/# Diskless PXE kiosks
+├── nix-surface.nix       # Surface Pro tablets
-│   ├── headless/       # Servers and containers
+├── nix-lxc.nix           # LXC containers
-│   └── ...
+├── nix-wsl.nix           # WSL instances
-├── installer/          # ISO and container builds
+├── nix-zima.nix          # ZimaBoard systems
-├── templates/          # Templates for external configs
+└── nix-ephemeral.nix     # Diskless/netboot systems
-│   ├── system/         # System configuration template
+
-│   └── user/           # User configuration template
+glue/                     # Fleet generation and common configuration
-├── docs/               # Documentation
+├── fleet.nix             # Processes inventory.nix to generate all hosts
-│   ├── INVENTORY.md    # Host configuration guide
+├── common.nix            # Common NixOS configuration (all hosts)
-│   ├── NAMESPACE.md    # Option reference
+├── boot.nix              # Boot and filesystem configuration
-│   ├── BUILDING.md     # Building artifacts
+└── user-config.nix       # User account and home-manager integration
-│   └── DEVELOPMENT.md  # Development guide
+
-└── assets/             # Assets (Plymouth theme, etc.)
+sw/                       # Software configurations by system type
+├── default.nix           # Software module entry point
+├── python.nix            # Python tools (pixi, uv)
+├── nvim.nix              # Neovim configuration
+├── ghostty.nix           # Ghostty terminal
+├── theme.nix             # System theme configuration
+├── updater.nix           # System update scripts
+├── update-ref.nix        # Update reference tracking
+├── builders/             # Build server configuration
+├── desktop/              # Desktop environment
+├── headless/             # Server/container without GUI
+├── tablet-kiosk/         # Surface tablet kiosk mode
+└── stateless-kiosk/      # Diskless PXE netboot systems
+
+installer/                # Build artifacts
+├── default.nix           # Build configuration
+├── artifacts.nix         # ISO/LXC/Proxmox definitions
+├── auto-install.nix      # Installer scripts
+├── modules.nix           # Installer-specific modules
+├── deploy-proxmox-lxc.sh # Proxmox deployment script
+└── PROXMOX_LXC.md        # Proxmox guide
+
+templates/                # Templates for external modules
+├── user/                 # User configuration template
+│   ├── user.nix          # User options + home-manager config
+│   └── README.md
+└── system/               # System configuration template
+    ├── default.nix       # NixOS module
+    └── README.md
+
+docs/                     # Documentation
+├── README.md             # This file
+├── INVENTORY.md          # Host configuration guide
+├── NAMESPACE.md          # Option reference
+├── USER_CONFIGURATION.md # User management
+├── EXTERNAL_MODULES.md   # External module integration
+├── BUILDING.md           # Build and deployment
+└── DEVELOPMENT.md        # Development workflow
+
+assets/                   # Assets
+└── plymouth-theme/       # Boot splash theme
 ```
 
 ## Configuration Overview
 
-All Innovation Factory options use the `athenix.*` namespace. See **[docs/NAMESPACE.md](docs/NAMESPACE.md)** for complete reference.
+All Innovation Factory-specific options use the `athenix` namespace to avoid conflicts with NixOS options.
 
-**Quick examples:**
+### Common Options
 
 ```nix
-# Host configuration
+# Host filesystem and hardware
-athenix.host.filesystem.device = "/dev/nvme0n1";
+athenix.host = {
-athenix.host.filesystem.swapSize = "64G";
+  filesystem.device = "/dev/sda";
+  filesystem.swapSize = "32G";
+  buildMethods = [ "installer-iso" ];
+  useHostPrefix = true;
+};
 
-# Software configuration  
+# System type and packages
-athenix.sw.type = "desktop";  # or "headless", "tablet-kiosk"
+athenix.sw = {
-athenix.sw.extraPackages = with pkgs; [ vim docker ];
+  type = "desktop";  # desktop, tablet-kiosk, stateless-kiosk, headless, builders
+  extraPackages = with pkgs; [ vim docker ];
+};
 
 # User management
 athenix.users.myuser.enable = true;
 athenix.forUser = "myuser";  # Convenience shortcut
 ```
 
-## Prerequisites
+See [docs/NAMESPACE.md](docs/NAMESPACE.md) for complete option reference.
-
-To work with this repository, install Nix with flakes support:
-
-```bash
-# Recommended: Determinate Systems installer (includes flakes)
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-
-# Alternative: Official installer (requires enabling flakes manually)
-sh <(curl -L https://nixos.org/nix/install) --daemon
-```
 
 ## Common Tasks
 
-### Adding a New User
-
-1. Edit `users.nix`:
-
-```nix
-myuser = {
-  description = "My Full Name";
-  extraGroups = [ "wheel" "networkmanager" ];
-  shell = pkgs.zsh;
-  hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
-  opensshKeys = [ "ssh-ed25519 AAAA... user@host" ];
-};
-```
-
-2. Enable on hosts in `inventory.nix`:
-
-```nix
-nix-laptop = {
-  devices = 2;
-  overrides.athenix.users.myuser.enable = true;
-};
-```
-
-**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete user management guide.**
-
 ### Adding Hosts
 
 Edit `inventory.nix`:
 
 ```nix
-# Simple: Create 5 laptops
+# Simple: Create 5 identical laptops
 nix-laptop = {
-  devices = 5;  # Creates nix-laptop1 through nix-laptop5
+  devices = 5;
 };
 
-# With configuration
+# With custom configuration per device
 nix-surface = {
   devices = {
     "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
@@ -158,107 +161,134 @@ nix-surface = {
   };
 };
 
-# With overrides for all devices
+# With common overrides
 nix-desktop = {
   devices = 3;
   overrides = {
     athenix.users.student.enable = true;
-    athenix.sw.extraPackages = with pkgs; [ vim ];
   };
 };
 ```
 
-**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete host configuration guide.**
+**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete guide.**
+
+### Managing Users
+
+Edit `users.nix`:
+
+```nix
+athenix.users.myuser = {
+  description = "My Name";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "$6$...";  # mkpasswd -m sha-512
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+};
+```
+
+Enable in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete guide.**
 
 ### Using External Configurations
 
-Users and systems can reference external Git repositories for configuration:
+Reference external repositories for user dotfiles or system configurations:
 
 ```nix
-# In users.nix - External dotfiles with user configuration
+# User dotfiles (in users.nix)
-myuser.external = builtins.fetchGit {
+hdh20267.external = builtins.fetchGit {
-  url = "https://git.factory.uga.edu/username/dotfiles";
+  url = "https://git.factory.uga.edu/hdh20267/dotfiles";
   rev = "abc123...";
 };
-# The external user.nix file contains both athenix.users.myuser options
-# AND home-manager configuration
 
-# In inventory.nix - External system config
+# System configuration (in inventory.nix)
 nix-lxc = {
-  devices."server" = builtins.fetchGit {
+  devices."special" = builtins.fetchGit {
     url = "https://git.factory.uga.edu/org/server-config";
     rev = "abc123...";
   };
 };
 ```
 
-**Create templates:**
-```bash
-# User configuration (dotfiles)
-nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
-
-# System configuration
-nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system
-```
-
 **See [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) for complete guide.**
 
 ### Building Installation Media
 
 ```bash
-# Build installer ISO
+# Build installer ISO for a specific host
-nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
+nix build .#installer-iso-nix-laptop1
 
 # Build LXC container
 nix build .#lxc-nix-builder
 
 # List all available artifacts
-nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
+nix flake show
 ```
 
-**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide on building ISOs, containers, and using remote builders.**
+**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.**
 
 ## System Types
 
+Set via `athenix.sw.type`:
+
 - **`desktop`** - Full GNOME desktop environment
-- **`tablet-kiosk`** - Surface tablets in kiosk mode
+- **`tablet-kiosk`** - Surface tablets with Firefox kiosk browser
-- **`stateless-kiosk`** - Diskless PXE boot kiosks  
+- **`stateless-kiosk`** - Diskless PXE-booted systems
-- **`headless`** - Servers and containers (no GUI)
+- **`headless`** - Servers and containers without GUI
+- **`builders`** - Build servers
 
-Set via `athenix.sw.type` option. See [docs/NAMESPACE.md](docs/NAMESPACE.md) for all options.
+## Development Workflow
 
-## Development
-
-**Quick commands:**
 ```bash
-nix flake check           # Validate all configurations
+# Check all configurations
-nix fmt                   # Format code
+nix flake check
-nix flake update          # Update dependencies
+
-nix build .#installer-iso-nix-laptop1  # Build specific artifact
+# Format code
+nix fmt **/*.nix
+
+# Build specific artifact
+nix build .#installer-iso-nix-laptop1
+
+# Update flake inputs
+nix flake update
 ```
 
-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development guide.**
+**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed workflow.**
 
 ## Troubleshooting
 
-**Common issues:**
+| Issue | Solution |
+|-------|----------|
+| Build errors | Run `nix flake check --show-trace` for details |
+| Configuration validation | `nix flake check` checks all 50+ hosts |
+| External modules fail | Verify Git URL accessibility and module structure |
+| Remote build issues | Test SSH: `ssh engr-ugaif@nix-builder` |
+| List all hosts | `nix eval .#nixosConfigurations --apply builtins.attrNames` |
+| Disk space | `nix-collect-garbage -d && nix store optimise` |
 
-- **Build errors:** Run `nix flake check --show-trace` for details
+## Prerequisites
-- **External modules not loading:** Check repository access and module structure (see templates)
+
-- **Remote build failures:** Test SSH access: `ssh engr-ugaif@nix-builder`
+Nix with flakes support:
-- **Out of disk space:** Run `nix-collect-garbage -d && nix store optimise`
 
-**Useful commands:**
 ```bash
-nix flake show                    # List all available outputs
+# Recommended: Determinate Systems installer
-nix flake metadata                # Show flake info
+curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-nix eval .#nixosConfigurations --apply builtins.attrNames  # List all hosts
+
+# Or enable flakes in existing Nix installation
+echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
 ```
 
-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/BUILDING.md](docs/BUILDING.md) for detailed troubleshooting.**
+## More Information
 
-## Getting Help
+- [docs/INVENTORY.md](docs/INVENTORY.md) - Host configuration
-
+- [docs/NAMESPACE.md](docs/NAMESPACE.md) - All option references
-- Review documentation in `docs/` directory
+- [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) - User management
-- Check templates: `templates/user/` and `templates/system/`  
+- [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) - External modules
-- Contact Innovation Factory IT team
+- [docs/BUILDING.md](docs/BUILDING.md) - Building and deployment
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - Development guide

docs/BUILDING.md

@@ -1,11 +1,13 @@
-# Building Installation Media
+# Building Installation Media and Artifacts
 
-This guide covers building installer ISOs, live images, and container artifacts from the nixos-systems flake.
+Guide to building installer ISOs, live images, and container artifacts.
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
 - [Available Artifacts](#available-artifacts)
+- [Building Locally](#building-locally)
+- [Building from Remote](#building-from-remote)
 - [Installer ISOs](#installer-isos)
 - [Live ISOs](#live-isos)
 - [Container Images](#container-images)
@@ -15,116 +17,194 @@ This guide covers building installer ISOs, live images, and container artifacts
 ## Quick Start
 
 ```bash
-# Build an installer ISO for a specific host
+# List all available artifacts
-nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
+nix flake show
 
-# Result will be in result/iso/
+# Build installer ISO for a specific host
+nix build .#installer-iso-nix-laptop1
+
+# Result is in result/iso/
 ls -lh result/iso/
 ```
 
 ## Available Artifacts
 
-List all available build outputs:
+Athenix can build multiple artifact types for deployment:
 
-```bash
+| Type | Description | Location | Use Case |
-nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
+|------|-------------|----------|----------|
+| `installer-iso-*` | Auto-install ISO | `result/iso/` | Install NixOS to disk |
+| `iso-*` | Live ISO | `result/iso/` | Boot without installing |
+| `ipxe-*` | PXE netboot | `result/` | Diskless netboot systems |
+| `lxc-*` | LXC container | `result/tarball/` | LXC/Proxmox containers |
+| `proxmox-*` | Proxmox VMA | `result/` | Proxmox VM templates |
+
+Set artifact types per-host via `athenix.host.buildMethods` in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.host.buildMethods = [ "installer-iso" ];
+};
+
+nix-lxc = {
+  devices.builder = {
+    athenix.host.buildMethods = [ "lxc" "proxmox" ];
+  };
+};
 ```
 
-Common artifact types:
+## Building Locally
 
-| Artifact Type | Description | Example |
+Build artifacts on your local machine:
-|--------------|-------------|---------|
-| `installer-iso-*` | Auto-install ISO that installs configuration to disk | `installer-iso-nix-laptop1` |
-| `iso-*` | Live ISO (bootable without installation) | `iso-nix-ephemeral1` |
-| `ipxe-*` | iPXE netboot artifacts (kernel, initrd, script) | `ipxe-nix-ephemeral1` |
-| `lxc-*` | LXC container tarball | `lxc-nix-builder` |
-| `proxmox-*` | Proxmox VMA archive | `proxmox-nix-builder` |
-
-## Installer ISOs
-
-Installer ISOs automatically install the NixOS configuration to disk on first boot.
-
-### Building Locally
 
 ```bash
-# Build installer for a specific host
+# Build installer ISO
 nix build .#installer-iso-nix-laptop1
 
-# Result location
-ls -lh result/iso/nixos-*.iso
-
-# Copy to USB drive (replace /dev/sdX with your USB device)
-sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress
-```
-
-### Building from Gitea
-
-```bash
-nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
-```
-
-### Using the Installer
-
-1. Boot from the ISO
-2. The system will automatically partition the disk and install NixOS
-3. After installation completes, remove the USB drive and reboot
-4. Log in with the configured user credentials
-
-**Note:** The installer will **erase all data** on the target disk specified in `athenix.host.filesystem.device`.
-
-## Live ISOs
-
-Live ISOs boot into a temporary system without installing to disk. Useful for:
-- Testing configurations
-- Recovery operations
-- Ephemeral/stateless systems
-
-### Building Live ISOs
-
-```bash
 # Build live ISO
 nix build .#iso-nix-ephemeral1
 
-# Result location
+# Build LXC container
-ls -lh result/iso/nixos-*.iso
+nix build .#lxc-nix-builder
+
+# Build all available outputs
+nix build .#
 ```
 
-### Stateless Kiosk Systems
+**Result locations:**
+- ISOs: `result/iso/nixos-*.iso`
+- LXC: `result/tarball/nixos-*.tar.xz`
+- Proxmox: `result/`
+- iPXE: `result/` (kernel, initrd, script)
 
-For PXE netboot kiosks, use the `ipxe-*` artifacts:
+### Build Specific Host
 
 ```bash
-# Build iPXE artifacts
+# Get list of all hosts
-nix build .#ipxe-nix-ephemeral1
+nix eval .#nixosConfigurations --apply builtins.attrNames
 
-# Result contains:
+# Build specific host
-# - bzImage (kernel)
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
-# - initrd (initial ramdisk)
+```
-# - netboot.ipxe (iPXE script)
+
-ls -lh result/
+## Building from Remote
+
+Build from the Gitea repository without cloning:
+
+```bash
+# Build installer ISO
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
+
+# Build LXC container
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#lxc-nix-builder
+
+# Use specific branch or revision
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git?ref=develop#installer-iso-nix-laptop1
+```
+
+## Installer ISOs
+
+Installer ISOs automatically partition and install NixOS on first boot.
+
+### Building
+
+```bash
+nix build .#installer-iso-nix-laptop1
+ls -lh result/iso/
+```
+
+### Burning to USB
+
+```bash
+# Find USB device (be careful!)
+lsblk
+
+# Burn ISO to USB (replace sdX with your device)
+sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress
+
+# Sync and eject
+sudo sync && sudo eject /dev/sdX
+```
+
+### Installation Process
+
+1. Boot from the USB drive
+2. System automatically boots into installer
+3. Installer partitions disk according to `athenix.host.filesystem`
+4. NixOS is installed and configured
+5. System reboots automatically
+6. Log in with configured user
+
+**Note:** Installer will erase all data on the target disk specified in `athenix.host.filesystem.device`.
+
+### Installer Configuration
+
+Customize installer via host configuration:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides = {
+    athenix.host.filesystem.device = "/dev/nvme0n1";
+    athenix.host.filesystem.swapSize = "32G";
+    athenix.host.buildMethods = [ "installer-iso" ];
+  };
+};
+```
+
+## Live ISOs
+
+Live ISOs boot into a temporary system without installing to disk.
+
+### Building
+
+```bash
+nix build .#iso-nix-ephemeral1
+```
+
+### Usage
+
+Live ISOs are useful for:
+- Testing configurations before installation
+- Recovery operations
+- Ephemeral/stateless systems
+- Booting in kiosk mode
+
+### Customizing Live ISO
+
+```nix
+nix-ephemeral = {
+  devices.live = {
+    athenix.sw.type = "stateless-kiosk";
+    athenix.sw.kioskUrl = "https://dashboard.example.com";
+    athenix.host.buildMethods = [ "iso" ];
+  };
+};
 ```
 
 ## Container Images
 
 ### LXC Containers
 
-Build LXC container tarballs for Proxmox or other LXC hosts:
+Build LXC container tarballs for Proxmox or standalone LXC:
 
 ```bash
-# Build LXC tarball
 nix build .#lxc-nix-builder
-
+ls -lh result/tarball/
-# Result location
-ls -lh result/tarball/nixos-*.tar.xz
 ```
 
-**Importing to Proxmox:**
+#### Importing to Proxmox
+
+1. Copy tarball to Proxmox host:
 
 ```bash
-# Copy tarball to Proxmox host
 scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/
+```
 
-# Create container from Proxmox CLI
+2. Create container:
+
+```bash
 pct create 100 local:vztmpl/nixos-*.tar.xz \
   --hostname nix-builder \
   --memory 4096 \
@@ -132,25 +212,59 @@ pct create 100 local:vztmpl/nixos-*.tar.xz \
   --net0 name=eth0,bridge=vmbr0,ip=dhcp
 ```
 
-See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed Proxmox deployment instructions.
+3. Start and log in:
+
+```bash
+pct start 100
+pct shell 100
+```
+
+#### Proxmox Integration
+
+For detailed Proxmox deployment instructions, see [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md).
 
 ### Proxmox VMA
 
 Build Proxmox-specific VMA archives:
 
 ```bash
-# Build Proxmox VMA
 nix build .#proxmox-nix-builder
-
-# Result location
 ls -lh result/
 ```
 
+VMA files can be imported directly into Proxmox for rapid VM creation.
+
+## iPXE / Network Boot
+
+Build iPXE artifacts for diskless PXE boot systems:
+
+```bash
+nix build .#ipxe-nix-ephemeral1
+ls -lh result/
+```
+
+Artifacts include:
+- `bzImage` - Linux kernel
+- `initrd` - Initial ramdisk
+- `netboot.ipxe` - iPXE boot script
+
+### iPXE Setup
+
+Configure your PXE server to boot from these artifacts:
+
+```ipxe
+kernel tftp://server/bzImage
+initrd tftp://server/initrd
+boot
+```
+
+See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed network boot setup.
+
 ## Remote Builders
 
 Speed up builds by offloading to build servers.
 
-### One-Time Remote Build
+### One-Time Build
 
 ```bash
 nix build .#installer-iso-nix-laptop1 \
@@ -159,7 +273,7 @@ nix build .#installer-iso-nix-laptop1 \
 
 ### Persistent Configuration
 
-Add to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`:
+Add to `~/.config/nix/nix.conf`:
 
 ```conf
 builders = ssh://engr-ugaif@nix-builder x86_64-linux
@@ -171,12 +285,12 @@ Then build normally:
 nix build .#installer-iso-nix-laptop1
 ```
 
-### SSH Key Setup
+### SSH Setup
 
-For remote builders, ensure SSH keys are configured:
+Ensure SSH is configured for the builder:
 
 ```bash
-# Generate SSH key if needed
+# Generate key if needed
 ssh-keygen -t ed25519
 
 # Copy to builder
@@ -188,77 +302,86 @@ ssh engr-ugaif@nix-builder
 
 ### Multiple Builders
 
-Configure multiple build servers:
-
 ```conf
-builders = ssh://engr-ugaif@nix-builder x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux
+builders = ssh://engr-ugaif@nix-builder1 x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux
 ```
 
+### Automatic Remote Build (Tablets)
+
+Surface tablets are configured to automatically use remote builders:
+
+```nix
+athenix.sw.remoteBuild = {
+  enable = true;
+  hosts = [ "nix-builder" ];
+};
+```
+
+This speeds up builds on resource-constrained devices.
+
 ## Troubleshooting
 
 ### Build Errors
 
-**Check configuration validity:**
+Get detailed error information:
+
 ```bash
+# Verbose error traces
+nix build .#installer-iso-nix-laptop1 --show-trace
+
+# Check all configurations first
 nix flake check --show-trace
 ```
 
-**Test specific host build:**
-```bash
-nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
-```
-
-### Remote Builder Issues
-
-**Test SSH access:**
-```bash
-ssh engr-ugaif@nix-builder
-```
-
-**Check builder disk space:**
-```bash
-ssh engr-ugaif@nix-builder df -h
-```
-
-**Temporarily disable remote builds:**
-
-In `inventory.nix`:
-```nix
-athenix.sw.remoteBuild.enable = false;
-```
-
 ### Out of Disk Space
 
-**Clean up Nix store:**
 ```bash
+# Clean up Nix store
 nix-collect-garbage -d
+
+# Optimize store
 nix store optimise
 ```
 
-**Check space:**
+### Build Hangs
+
 ```bash
-df -h /nix
+# List processes
+ps aux | grep nix
+
+# Cancel build
+Ctrl+C
 ```
 
-### ISO Won't Boot
+### Finding Artifact Outputs
 
-**Verify ISO integrity:**
 ```bash
-sha256sum result/iso/nixos-*.iso
+# List all buildable outputs
+nix flake show
+
+# Check specific output exists
+nix flake show | grep installer-iso-nix-laptop1
+
+# Get path to output
+nix build .#installer-iso-nix-laptop1 --no-link
 ```
 
-**Check USB write:**
+### Build Not Creating Expected File
-```bash
-# Use correct block size and sync
-sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress && sync
-```
 
-**Try alternative boot mode:**
+```bash
-- UEFI systems: Try legacy BIOS mode
+# Check build log
-- Legacy BIOS: Try UEFI mode
+nix build .#installer-iso-nix-laptop1 -L
+
+# Check what's in result
+ls -la result/
+
+# Inspect NixOS build structure
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
+```
 
 ## See Also
 
+- [DEVELOPMENT.md](DEVELOPMENT.md) - Development workflow
+- [INVENTORY.md](INVENTORY.md) - Host configuration
+- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment
 - [README.md](../README.md) - Main documentation
-- [INVENTORY.md](INVENTORY.md) - Host configuration guide
-- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment guide

docs/DEVELOPMENT.md

@@ -1,464 +1,456 @@
 # Development Guide
 
-This guide covers development workflows for maintaining and extending the nixos-systems repository.
+Comprehensive guide for maintaining and extending Athenix.
 
 ## Table of Contents
 
 - [Prerequisites](#prerequisites)
+- [Development Workflow](#development-workflow)
 - [Testing Changes](#testing-changes)
 - [Continuous Integration](#continuous-integration)
-- [System Rebuilds](#system-rebuilds)
+- [Common Tasks](#common-tasks)
-- [Updating Dependencies](#updating-dependencies)
+- [Debugging](#debugging)
-- [Adding Packages](#adding-packages)
+- [Troubleshooting](#troubleshooting)
-- [Python Development](#python-development)
-- [Contributing](#contributing)
 
 ## Prerequisites
 
-Install Nix with flakes support:
+### Install Nix with Flakes
 
 ```bash
-# Recommended: Determinate Systems installer (includes flakes)
+# Recommended: Determinate Systems installer
 curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
 
-# Alternative: Official installer (requires enabling flakes manually)
+# Or official installer
 sh <(curl -L https://nixos.org/nix/install) --daemon
+
+# Enable flakes in existing installation
+mkdir -p ~/.config/nix
+echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
+```
+
+### Clone Repository
+
+```bash
+git clone https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
+cd athenix
+
+# Optional: enable direnv for automatic Nix environment
+direnv allow
+```
+
+## Development Workflow
+
+### Making Changes
+
+1. **Edit configuration files** - Modify `inventory.nix`, `users.nix`, or host/software config
+
+2. **Validate** - Check syntax and configuration
+
+```bash
+nix flake check
+```
+
+3. **Format code** - Apply consistent formatting
+
+```bash
+nix fmt
+```
+
+4. **Test** - Build specific artifacts or configurations
+
+```bash
+# Test specific host
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
+
+# Or build an artifact
+nix build .#installer-iso-nix-laptop1
+```
+
+5. **Commit and push**
+
+```bash
+git add .
+git commit -m "Brief description of changes"
+git push
+```
+
+### Example: Adding a New User
+
+1. Define user in `users.nix`:
+
+```nix
+athenix.users.newuser = {
+  description = "New User";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "...";  # mkpasswd -m sha-512
+};
+```
+
+2. Enable on fleet in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.newuser.enable = true;
+};
+```
+
+3. Validate and commit:
+
+```bash
+nix flake check
+nix fmt
+git add . && git commit -m "Add newuser account"
+git push
 ```
 
 ## Testing Changes
 
-Always test configuration changes before committing.
+### Validate Configuration Syntax
 
-### Validate All Configurations
+Always run before committing:
 
 ```bash
-# Check all configurations build correctly
 nix flake check
+```
 
-# Check with verbose error traces
+Shows any configuration errors across all ~50+ hosts. Output:
-nix flake check --show-trace
+
+```
+checking 50 configurations...
+✓ All checks passed
 ```
 
 ### Test Specific Host Build
 
 ```bash
-# Build a specific host's configuration
+# Build specific host (shows if config actually compiles)
 nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
 
-# Build installer for specific host
+# Shorter form
-nix build .#installer-iso-nix-laptop1
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
 ```
 
-### Test Local Changes
+### Test Installer Build
-
-If you're on a NixOS system managed by this flake:
 
 ```bash
-# Test changes without committing (temporary, doesn't survive reboot)
+# Test that installer ISO builds
+nix build .#installer-iso-nix-laptop1 -L
+```
+
+### Test on Running NixOS System
+
+If you're on a NixOS system managed by Athenix:
+
+```bash
+# Test changes temporarily (won't survive reboot)
 sudo nixos-rebuild test --flake .
 
-# Apply and switch to new configuration
+# Apply and switch (persistent)
 sudo nixos-rebuild switch --flake .
 
 # Build without switching
 sudo nixos-rebuild build --flake .
+
+# Show what will change
+sudo nixos-rebuild dry-activate --flake .
+```
+
+### Rollback
+
+If a build breaks your system:
+
+```bash
+# List recent generations
+nix-env --list-generations
+
+# Rollback to previous generation
+nix-env --rollback
+
+# Or switch to specific generation
+nix-env --switch-generation 42
 ```
 
 ## Continuous Integration
 
-The repository uses Gitea Actions for automated testing and validation. CI jobs run on the self-hosted `nix-builder` machine.
+### CI Pipeline
 
-### CI Workflow
+All pushes and pull requests trigger automated tests on the self-hosted `nix-builder`:
 
-All pull requests and pushes to main trigger the CI pipeline, which includes:
+1. **Flake Check** - `nix flake check` validates all 50+ configurations
-
+2. **Format Check** - Verifies code formatted with `nix fmt`
-1. **Flake Check** - Validates all NixOS configurations
+3. **Build Key Hosts** - Builds `nix-builder`, `nix-laptop1`, `nix-desktop1`
-   - Runs `nix flake check` to ensure all systems build correctly
+4. **Build Artifacts** - Tests `lxc-nix-builder` and `installer-iso-nix-laptop1`
-   - Catches configuration errors early
-
-2. **Format Check** - Ensures code formatting consistency
-   - Verifies code is formatted with `nix fmt`
-   - Automatically fails if formatting is incorrect
-
-3. **Build Key Configurations** - Tests critical system builds
-   - Builds: `nix-builder`, `nix-laptop1`, `nix-desktop1`
-   - Ensures core configurations compile successfully
-
-4. **Build Artifacts** - Validates installer and container builds
-   - Builds: `lxc-nix-builder`, `installer-iso-nix-laptop1`
-   - Verifies deployment artifacts are buildable
 
 ### Viewing CI Status
 
-Check the CI status badge at the top of the README or view detailed logs:
-
 ```bash
-# View workflow status
+# Web interface
 https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions
+
+# Or check locally
+git log --oneline -n 5
+# Look for ✓ or ✗ next to commits
 ```
 
 ### Running CI Checks Locally
 
-Before pushing changes, run the same checks that CI performs:
+Test before pushing:
 
 ```bash
-# Run all checks
+# Flake check
 nix flake check --show-trace
 
-# Check formatting
+# Format check
-nix fmt
+nix fmt --check
-git diff --exit-code  # Should return no changes
 
-# Build specific configuration
+# Format code
-nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel
+nix fmt **/*.nix
 
-# Build artifacts
+# Build key configurations
-nix build .#lxc-nix-builder
+nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel -L
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
 ```
 
-### Self-Hosted Runner
+## Common Tasks
 
-CI jobs run on the `nix-builder` host as a self-hosted Gitea Actions runner. This provides:
+### Adding a New Host
 
-- Native Nix environment without installation overhead
+Edit `inventory.nix`:
-- Access to local Nix store for faster builds
-- Consistent build environment matching deployment targets
-- Direct access to build caching infrastructure
 
-#### Setting Up the Gitea Actions Runner
+```nix
-
+nix-surface = {
-The nix-builder host is configured with a Gitea Actions self-hosted runner in `inventory.nix`. To complete the setup:
+  devices = 3;  # Creates nix-surface1, nix-surface2, nix-surface3
-
+  overrides = {
-1. **Generate a Gitea Runner Token**:
+    athenix.sw.type = "tablet-kiosk";
-   - Go to https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners
+    athenix.sw.kioskUrl = "https://dashboard.example.com";
-   - Click "Create new Runner"
+  };
-   - Copy the registration token
+};
-
-2. **Create the token file on nix-builder**:
-   ```bash
-   ssh engr-ugaif@nix-builder
-   echo "YOUR_TOKEN_HERE" | sudo tee /var/lib/gitea-runner-token > /dev/null
-   sudo chmod 600 /var/lib/gitea-runner-token
 ```
 
-3. **Rebuild the system** to start the runner:
+Test:
-   ```bash
-   sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#nix-builder
-   ```
-
-4. **Verify the runner is registered**:
-   - Check https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners
-   - The runner should appear with the `nix-builder` label
-
-The runner service is configured in the nix-builder device configuration and will automatically:
-- Register with the repository on first start
-- Use the `nix-builder` label for workflow targeting
-- Run as the `engr-ugaif` user
-- Store work in `/var/lib/gitea-runner`
-
-### Troubleshooting CI Failures
-
-If CI fails:
-
-1. **Check the error logs** in the Gitea Actions tab
-2. **Run the same command locally** to reproduce the issue
-3. **Use `--show-trace`** for detailed error information
-4. **Verify formatting** with `nix fmt` if format check fails
-5. **Check for external dependencies** that might be unavailable
-
-Common CI issues:
-
-- **Flake check fails**: Configuration error in a host definition
-- **Format check fails**: Run `nix fmt` locally and commit changes
-- **Build fails**: Missing dependency or syntax error in Nix expressions
-- **Cache issues**: Usually self-resolving; can retry the workflow
-
-## System Rebuilds
-
-### From Local Directory
 
 ```bash
-# Rebuild current host from local directory
-sudo nixos-rebuild switch --flake .
-
-# Rebuild specific host
-sudo nixos-rebuild switch --flake .#nix-laptop1
-
-# Test without switching (temporary, doesn't persist reboot)
-sudo nixos-rebuild test --flake .#nix-laptop1
-
-# Build a new generation without activating it
-sudo nixos-rebuild build --flake .
-```
-
-### From GitHub
-
-```bash
-# Rebuild from GitHub main branch
-sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
-
-# Use --impure for external user configurations with fetchGit
-sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git --impure
-
-# Rebuild specific host from GitHub
-sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#nix-laptop1
-```
-
-### Boot into Previous Generation
-
-If something breaks:
-
-```bash
-# List generations
-sudo nixos-rebuild list-generations
-
-# Rollback to previous generation
-sudo nixos-rebuild switch --rollback
-
-# Or select specific generation at boot (GRUB menu)
-# Reboot and select "NixOS - Configuration X" from boot menu
-```
-
-## Updating Dependencies
-
-### Update All Inputs
-
-```bash
-# Update all flake inputs (nixpkgs, home-manager, etc.)
-nix flake update
-
-# Review changes
-git diff flake.lock
-
-# Test the updates
 nix flake check
-
+nix build .#installer-iso-nix-surface1 -L
-# Commit if successful
-git add flake.lock
-git commit -m "Update flake inputs"
-git push
 ```
 
-### Update Specific Input
+### Modifying Software Configuration
+
+Edit appropriate file in `sw/`:
 
 ```bash
-# Update only nixpkgs
+# Desktop software
-nix flake lock --update-input nixpkgs
-
-# Update home-manager
-nix flake lock --update-input home-manager
-
-# Update multiple specific inputs
-nix flake lock --update-input nixpkgs --update-input home-manager
-```
-
-### Check for Security Updates
-
-```bash
-# After updating, check for known vulnerabilities
-nix flake check
-
-# Review nixpkgs changelog
-git log HEAD..nixpkgs/nixos-25.11 --oneline | head -20
-```
-
-## Adding Packages
-
-### System-Wide Packages by Type
-
-Add packages based on system type:
-
-**Desktop systems:**
-```bash
-# Edit sw/desktop/programs.nix
 vim sw/desktop/programs.nix
+
+# Or for all systems
+vim sw/default.nix
 ```
 
-**Tablet kiosks:**
+Use `athenix.sw.extraPackages` for host-specific additions:
-```bash
-# Edit sw/tablet-kiosk/programs.nix
-vim sw/tablet-kiosk/programs.nix
-```
-
-**Headless systems:**
-```bash
-# Edit sw/headless/programs.nix
-vim sw/headless/programs.nix
-```
-
-### Packages for Specific Hosts
-
-Add to `athenix.sw.extraPackages` in `inventory.nix`:
 
 ```nix
 nix-laptop = {
-  devices = 2;
+  devices = 5;
-  overrides = {
+  overrides.athenix.sw.extraPackages = with pkgs; [ special-tool ];
-    athenix.sw.extraPackages = with pkgs; [
+};
-      vim
+```
-      docker
+
-      kubernetes-helm
+### Adding a System Type
+
+Create new type in `sw/`:
+
+```bash
+mkdir -p sw/my-type
+touch sw/my-type/{default.nix,programs.nix,services.nix}
+```
+
+Then reference in `sw/default.nix`:
+
+```nix
+{
+  imports = [
+    ./my-type/default.nix
+    # ... other types
   ];
+}
+```
+
+### Using External Configurations
+
+For user dotfiles:
+
+```nix
+# users.nix
+athenix.users.myuser.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/username/dotfiles";
+  rev = "abc123...";  # Pin to commit
+};
+```
+
+For system config:
+
+```nix
+# inventory.nix
+nix-lxc = {
+  devices."server".external = builtins.fetchGit {
+    url = "https://git.factory.uga.edu/org/server-config";
+    rev = "abc123...";
   };
 };
 ```
 
-### User-Specific Packages
+### Updating Dependencies
-
-Add to user's home-manager configuration in their external `user.nix`:
-
-```nix
-# In external user.nix
-home.packages = with pkgs; [
-  ripgrep
-  fd
-  bat
-];
-```
-
-### Search for Packages
 
 ```bash
-# Search nixpkgs
+# Update all flake inputs
-nix search nixpkgs firefox
+nix flake update
-nix search nixpkgs python3
 
-# Show package details
+# Update specific input
-nix eval nixpkgs#firefox.meta.description
+nix flake update nixpkgs
+
+# Show what changed
+git diff flake.lock
+
+# Test after update
+nix flake check --show-trace
+
+# If tests pass, commit
+git add flake.lock && git commit -m "Update dependencies"
 ```
 
-## Python Development
+## Debugging
 
-All systems include modern Python tools: `pixi` and `uv`.
+### Verbose Output
 
-### Pixi (Recommended for Projects)
+Get detailed error messages:
 
 ```bash
-# Initialize new project
+# Show full error traces
-pixi init my-project
+nix flake check --show-trace
-cd my-project
 
-# Add dependencies
+# With maximum verbosity
-pixi add pandas numpy matplotlib jupyter
+nix build .#installer-iso-nix-laptop1 -vvv
 
-# Run Python
+# Show build log
-pixi run python
+nix build .#installer-iso-nix-laptop1 -L
-
-# Run Jupyter
-pixi run jupyter notebook
-
-# Run scripts
-pixi run python script.py
-
-# Shell with dependencies
-pixi shell
 ```
 
-### uv (Quick Virtual Environments)
+### Inspect Configuration
 
 ```bash
-# Create virtual environment
+# Evaluate configuration for specific host
-uv venv
+nix eval .#nixosConfigurations.nix-laptop1.config.athenix.sw --json
 
-# Activate
+# Get all host names
-source .venv/bin/activate
+nix eval .#nixosConfigurations --apply builtins.attrNames
 
-# Install packages
+# Check specific option
-uv pip install requests pandas
+nix eval .#nixosConfigurations.nix-laptop1.config.users.users
-
-# Freeze requirements
-uv pip freeze > requirements.txt
-
-# Install from requirements
-uv pip install -r requirements.txt
 ```
 
-### System Python
+### Test Module Loading
-
-Python development tools are configured in `sw/python.nix` and can be controlled via:
-
-```nix
-athenix.sw.python.enable = true;  # Default: enabled
-```
-
-## Contributing
-
-### Code Style
-
-- Run formatter before committing: `nix fmt`
-- Follow existing code structure and conventions
-- Add comments for complex logic
-- Use the `athenix.*` namespace for all custom options
-
-### Testing Workflow
-
-1. Make changes
-2. Run formatter: `nix fmt`
-3. Test locally: `nix flake check`
-4. Test specific builds if needed
-5. Commit changes
-6. Push to GitHub
 
 ```bash
-# Full workflow
+# Evaluate specific module
-nix fmt
+nix-build -A nixosConfigurations.nix-laptop1.config.system.build.toplevel
-nix flake check
+
-git add .
+# Or with flakes
-git commit -m "Description of changes"
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel --verbose
-git push
 ```
 
-### Documentation
+### Check Derivation Dependencies
-
-Update relevant documentation when making changes:
-
-- `README.md` - Overview and quick start
-- `docs/INVENTORY.md` - Inventory configuration
-- `docs/NAMESPACE.md` - Configuration options
-- `USER_CONFIGURATION.md` - User management
-- `EXTERNAL_MODULES.md` - External modules
-
-### Creating Issues
-
-When reporting bugs or requesting features:
-
-1. Check existing issues first
-2. Provide clear description
-3. Include error messages and traces
-4. Specify which hosts are affected
-5. Include `flake.lock` info if relevant
-
-## Useful Commands
 
 ```bash
-# Show all available outputs
+# Show what dependencies a build needs
-nix flake show
+nix show-derivation .#installer-iso-nix-laptop1
 
-# Evaluate specific option
+# Or human-readable
-nix eval .#nixosConfigurations.nix-laptop1.config.networking.hostName
+nix build .#installer-iso-nix-laptop1 --dry-run
+```
 
+## Troubleshooting
+
+### Common Errors
+
+#### "Evaluation error"
+
+```
+error: evaluation aborted with the following error message: '...'
+```
+
+**Solution:** Check syntax in modified files. Use `nix fmt` and `nix flake check --show-trace`.
+
+#### "Unknown variable" or "Option does not exist"
+
+```
+error: The option `athenix.xyz' does not exist.
+```
+
+**Solution:** Check NAMESPACE.md for available options. Options must be in `athenix.*` namespace.
+
+#### "Hash mismatch" (for external modules)
+
+```
+error: Hash mismatch in fetched input
+```
+
+**Solution:** Update the pin. For `builtins.fetchGit`, use actual commit hash. Or:
+
+```bash
+nix flake update
+```
+
+#### Build runs out of memory
+
+```bash
+# Reduce parallel jobs
+nix build . --max-jobs 1
+```
+
+#### "No such file or directory" in build
+
+```bash
+# Check path exists
+ls -la /path/to/file
+
+# Or check relative to repo
+ls -la sw/my-file.nix
+```
+
+### Helpful Diagnostics
+
+```bash
 # List all hosts
 nix eval .#nixosConfigurations --apply builtins.attrNames
 
-# Check flake metadata
+# Show flake structure
-nix flake metadata
+nix flake show | head -50
 
-# Show evaluation trace
+# Check Nix store size
-nix eval --show-trace .#nixosConfigurations.nix-laptop1
+du -sh /nix/store
 
-# Build and enter debug shell
+# List top space users in store
-nix develop
+nix store du --human-readable | head -20
 
-# Clean up old generations
+# Find store paths for a package
-nix-collect-garbage -d
+nix store path-info -rS $(which some-package)
-
-# Optimize Nix store
-nix store optimise
 ```
 
+### Getting Help
+
+1. **Check documentation** - Review relevant doc file
+2. **Look at existing examples** - Check `inventory.nix` or `users.nix`
+3. **Search for similar patterns** - `grep -r "athenix.option" .`
+4. **Run tests locally** - `nix flake check --show-trace` with full output
+5. **Review git history** - `git log --patch -- filename.nix`
+
 ## See Also
 
-- [README.md](../README.md) - Main documentation
+- [BUILDING.md](BUILDING.md) - Building artifacts
-- [INVENTORY.md](INVENTORY.md) - Host inventory configuration
+- [INVENTORY.md](INVENTORY.md) - Host configuration
-- [BUILDING.md](BUILDING.md) - Building installation media
+- [NAMESPACE.md](NAMESPACE.md) - Configuration options
 - [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External modules
+- [README.md](../README.md) - Main documentation

docs/EXTERNAL_MODULES.md

@@ -1,6 +1,6 @@
 # External Configuration Modules
 
-This guide explains how to use external modules for system and user configurations in nixos-systems.
+Guide to using external modules for system and user configurations.
 
 ## Table of Contents
 
@@ -8,116 +8,141 @@ This guide explains how to use external modules for system and user configuratio
 - [System Modules](#system-modules)
 - [User Modules](#user-modules)
 - [Fetch Methods](#fetch-methods)
-- [Templates](#templates)
+- [Creating External Modules](#creating-external-modules)
-- [Integration Details](#integration-details)
+- [Best Practices](#best-practices)
 
 ## Overview
 
-External modules allow you to maintain configurations in separate Git repositories and reference them from `inventory.nix` (for systems) or `users.nix` (for users).
+External modules allow you to maintain configurations in separate Git repositories and reference them from Athenix.
 
 **Benefits:**
-- **Separation:** Keep configs in separate repositories
+- **Separation** - Keep complex configs in separate repositories
-- **Versioning:** Pin to specific commits for reproducibility
+- **Reproducibility** - Pin specific commits for deterministic builds
-- **Reusability:** Share configurations across deployments
+- **Reusability** - Share configurations across multiple deployments
-- **Flexibility:** Mix external modules with local overrides
+- **Flexibility** - Mix external modules with local configuration
+- **Ownership** - Users maintain their own dotfiles
 
 ## System Modules
 
-External system modules provide complete NixOS configurations for hosts.
+External system modules provide host-specific NixOS configurations.
 
-### Usage in inventory.nix
+### Usage
+
+In `inventory.nix`, reference an external module using the `external` field:
 
 ```nix
 nix-lxc = {
   devices = {
-    # Traditional inline configuration
+    # Inline configuration (traditional method)
     "local-server" = {
-      athenix.users.admin.enable = true;
+      athenix.sw.type = "headless";
       services.nginx.enable = true;
     };
     
-    # External module from Git
+    # External module (lazy evaluation - fetched only when building this host)
-    "remote-server" = builtins.fetchGit {
+    "remote-server".external = builtins.fetchGit {
       url = "https://git.factory.uga.edu/org/server-config";
-      rev = "abc123...";  # Pin to specific commit
+      rev = "abc123def456...";  # Must pin to specific commit
+    };
+    
+    # External module with additional local config
+    "mixed-server" = {
+      external = builtins.fetchGit {
+        url = "https://git.factory.uga.edu/org/server-config";
+        rev = "abc123def456...";
+      };
+      # Additional local overrides
+      athenix.users.admin.enable = true;
+      services.openssh.permitRootLogin = "no";
     };
   };
 };
 ```
 
-### External Repository Structure
+**Key Features:**
+- **Lazy Evaluation**: External modules are only fetched when building the specific host
+- **Efficient Rebuilds**: Other hosts can be rebuilt without fetching unrelated external modules
+- **Submodule Support**: Works with Git submodules without affecting other hosts
+
+### Repository Structure
 
 ```
 server-config/
 ├── default.nix     # Required: NixOS module
-└── README.md      # Optional: Documentation
+├── README.md       # Recommended: Documentation
+└── optional/
+    ├── config/     # Optional: Configuration files
+    └── scripts/    # Optional: Helper scripts
 ```
 
-**default.nix:**
+### Module Content (default.nix)
+
 ```nix
+# The module receives inputs and standard NixOS module parameters
 { inputs, ... }:
 { config, lib, pkgs, ... }:
 {
   # Your NixOS configuration
+  # Use any standard NixOS option or athenix.* options
+  
   services.nginx = {
     enable = true;
     virtualHosts."example.com" = {
       root = "/var/www";
+      forceSSL = true;
+      enableACME = true;
     };
   };
   
-  # Use athenix namespace options
+  # Use athenix options
-  athenix.users.admin.enable = true;
   athenix.sw.type = "headless";
+  athenix.sw.extraPackages = with pkgs; [ git htop ];
+  
+  # Standard NixOS configuration
+  networking.firewall.allowedTCPPorts = [ 80 443 ];
+  services.openssh.enable = true;
 }
 ```
 
-### What External Modules Receive
+### What System Modules Receive
 
-- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.)
+- **`inputs`** - All flake inputs (nixpkgs, home-manager, disko, etc.)
-- **`config`** - Full NixOS configuration
+- **`config`** - Current NixOS configuration (read/write)
 - **`lib`** - Nixpkgs library functions
 - **`pkgs`** - Package set
 
-### Module Integration Order
+### Configuration Order
 
-When a host is built, modules are loaded in this order:
+When a host is built, modules load in this order:
 
-1. User NixOS modules (from `users.nix` - `nixos.nix` files)
+1. Hardware type module (from `variants/nix-*.nix`)
-2. Host type module (from `hosts/types/`)
+2. Common system configuration (from `glue/common.nix`)
-3. Configuration overrides (from `inventory.nix`)
+3. Software type module (from `sw/{type}/`)
-4. Hostname assignment
+4. User NixOS modules (from `users.nix` - `nixos.nix` files)
-5. External system module (if using `builtins.fetchGit`)
+5. Device-specific overrides (from `inventory.nix`)
+6. External system module (if present)
 
-Later modules can override earlier ones using standard NixOS module precedence.
+Each later module can override earlier ones using standard NixOS precedence rules.
-
-### Template
-
-Create a new system module:
-
-```bash
-nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system
-```
-
-See [templates/system/](../templates/system/) for the complete template.
 
 ## User Modules
 
-External user modules provide home-manager configurations (dotfiles, packages, programs).
+External user modules provide home-manager configurations (dotfiles, environment setup).
 
-### Usage in users.nix
+### Usage
+
+In `users.nix`, reference an external user module:
 
 ```nix
 athenix.users = {
-  # External user module (dotfiles, home-manager, and user options)
+  # External user module
-  myuser = builtins.fetchGit {
+  myuser.external = builtins.fetchGit {
     url = "https://git.factory.uga.edu/username/dotfiles";
-    rev = "abc123...";
+    rev = "abc123def456...";  # Pin to specific commit
   };
 
   # Inline user definition
-  inlineuser = {
+  otheruser = {
-    description = "Inline User";
+    description = "Other User";
     extraGroups = [ "wheel" ];
     shell = pkgs.zsh;
     hashedPassword = "$6$...";
@@ -125,148 +150,179 @@ athenix.users = {
 };
 ```
 
-### External Repository Structure
+Then enable on hosts in `inventory.nix`:
 
-```
-dotfiles/
-├── user.nix     # Required: User options AND home-manager config
-├── nixos.nix    # Optional: System-level config
-└── config/      # Optional: Actual dotfiles
-    ├── bashrc
-    └── vimrc
-```
-
-**user.nix (required):**
 ```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+### Repository Structure
+
+```
+my-dotfiles/
+├── user.nix         # Required: User options + home-manager config
+├── nixos.nix        # Optional: System-level configuration
+├── README.md        # Recommended: Documentation
+└── config/          # Optional: Your actual dotfiles
+    ├── zshrc
+    ├── vimrc
+    ├── nvim/
+    └── ...
+```
+
+### user.nix (Required)
+
+Provides both user account settings AND home-manager configuration:
+
+```nix
+# Receives { inputs } and standard home-manager module parameters
 { inputs, ... }:
 { config, lib, pkgs, osConfig ? null, ... }:
 {
   # ========== User Account Configuration ==========
+  # These options define the user account itself
+  
   athenix.users.myusername = {
-    description = "Your Full Name";
+    description = "My Full Name";
+    extraGroups = [ "wheel" "docker" ];
     shell = pkgs.zsh;
-    hashedPassword = "!";
+    hashedPassword = "!";  # SSH keys only
-    opensshKeys = [ "ssh-ed25519 AAAA..." ];
+    opensshKeys = [
+      "ssh-ed25519 AAAA... user@laptop"
+    ];
     useZshTheme = true;
     useNvimPlugins = true;
   };
 
   # ========== Home Manager Configuration ==========
+  # User environment, packages, and dotfiles
+  
   # Packages
   home.packages = with pkgs; [
     vim
     git
-    htop
+    ripgrep
+    fzf
   ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox;
 
+  # Programs
   programs.git = {
     enable = true;
     userName = "My Name";
     userEmail = "me@example.com";
+    extraConfig = {
+      init.defaultBranch = "main";
+      core.editor = "vim";
+    };
+  };
+
+  programs.zsh = {
+    enable = true;
+    initExtra = ''
+      # Your Zsh configuration
+      export EDITOR=vim
+    '';
   };
 
   # Manage dotfiles
-  home.file.".bashrc".source = ./dotfiles/bashrc;
+  home.file.".zshrc".source = ./config/zshrc;
+  home.file.".vimrc".source = ./config/vimrc;
+  home.file.".config/nvim".source = ./config/nvim;
+
+  # Services
+  services.gpg-agent.enable = true;
 }
 ```
 
-**nixos.nix (optional):**
+### nixos.nix (Optional)
+
+System-level configuration for this user (rarely needed):
+
 ```nix
 { inputs, ... }:
 { config, lib, pkgs, ... }:
 {
-  # System-level configuration for this user
+  # System-level configuration
-  users.users.myuser.extraGroups = [ "docker" ];
+  # Only needed if the user requires specific system-wide settings
+  
+  users.users.myusername.extraGroups = [ "docker" ];
   environment.systemPackages = [ pkgs.docker ];
+  
+  # Security settings
+  security.sudo.extraRules = [{
+    users = [ "myusername" ];
+    commands = [{
+      command = "/usr/bin/something";
+      options = [ "NOPASSWD" ];
+    }];
+  }];
 }
 ```
 
 ### What User Modules Receive
 
 **In user.nix:**
-- **`inputs`** - Flake inputs (nixpkgs, home-manager, etc.)
+- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.)
-- **`config`** - Home-manager configuration
+- **`config`** - Home-manager configuration (read/write)
 - **`lib`** - Nixpkgs library functions
 - **`pkgs`** - Package set
-- **`osConfig`** - OS-level configuration (read-only)
+- **`osConfig`** - OS configuration (read-only) - useful for conditional setup
 
 **In nixos.nix:**
 - **`inputs`** - Flake inputs
-- **`config`** - NixOS configuration
+- **`config`** - NixOS configuration (read/write)
 - **`lib`** - Nixpkgs library functions
 - **`pkgs`** - Package set
 
-### User Options in users.nix
+### Conditional Setup Example
+
+Use `osConfig` to conditionally set up dotfiles based on the system type:
 
 ```nix
-username = {
+# In user.nix
-  # Identity
+{ inputs, ... }:
-  description = "Full Name";
+{ config, lib, pkgs, osConfig ? null, ... }:
+{
+  athenix.users.myuser = { /* ... */ };
 
-  # External configuration
+  # Install Firefox only on desktop systems
-  external = builtins.fetchGit { ... };
+  home.packages = with pkgs; [
-  # System settings
+    ripgrep
-  extraGroups = [ "wheel" "networkmanager" ];
+  ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox;
-  hashedPassword = "$6$...";
-  opensshKeys = [ "ssh-ed25519 ..." ];
-  shell = pkgs.zsh;
 
-  # Theme integration
+  # Different shell config per system
-  useZshTheme = true;      # Apply system zsh theme (default: true)
+  programs.zsh.initExtra = ''
-  useNvimPlugins = true;   # Apply system nvim config (default: true)
+    ${lib.optionalString (osConfig.athenix.sw.type or null == "headless") "
-  
+      # Headless-only settings
-  # Enable on specific systems (see docs/INVENTORY.md)
+    "}
-  enable = false;  # Set in inventory.nix via athenix.users.username.enable
+  '';
-};
+}
 ```
 
-### Template
-
-Create a new user module:
-
-```bash
-nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
-```
-
-See [templates/user/](../templates/user/) for the complete template.
-
 ## Fetch Methods
 
-### Recommended: fetchGit with Revision
+### builtins.fetchGit (Recommended)
 
-Pin to a specific commit for reproducibility:
+Pin to a specific Git revision:
 
 ```nix
 builtins.fetchGit {
-  url = "https://github.com/user/repo";
+  url = "https://git.factory.uga.edu/username/dotfiles";
-  rev = "abc123def456...";  # Full commit hash (40 characters)
+  rev = "abc123def456...";  # Required: specific commit hash
-  ref = "main";              # Optional: branch name
 }
 ```
 
-**Finding the commit hash:**
+**Advantages:**
-```bash
+- Reproducible (pinned to exact commit)
-# Latest commit on main branch
+- Works with any Git repository
-git ls-remote https://github.com/user/repo main
+- Supports SSH or HTTPS URLs
 
-# Or from a local clone
+**Important:** Always specify `rev` (commit hash) for reproducibility. Don't use branches which can change.
-git rev-parse HEAD
-```
 
-### fetchGit with Branch (Less Reproducible)
+### builtins.fetchTarball
-
-Always fetches latest from branch:
-
-```nix
-builtins.fetchGit {
-  url = "https://github.com/user/repo";
-  ref = "develop";
-}
-```
-
-⚠️ **Warning:** Builds may not be reproducible as the branch HEAD can change.
-
-### fetchTarball (For Releases)
 
 Download specific release archives:
 
@@ -287,174 +343,141 @@ nix-prefetch-url --unpack https://github.com/user/repo/archive/v1.0.0.tar.gz
 Use local directories during development:
 
 ```nix
-/home/username/dev/my-config
+# users.nix
+athenix.users.myuser.external = /home/user/my-dotfiles;
 
-# Or relative to repository
+# inventory.nix
-./my-local-config
+nix-laptop = {
+  devices = {
+    "dev".athenix.users.myuser.enable = true;
+  };
+};
 ```
 
-⚠️ **Warning:** Only for testing. Use Git-based methods for production.
+**Note:** Only works if the path exists on the machine running `nix flake check` or `nix build`.
 
-## Templates
+## Creating External Modules
 
 ### System Module Template
 
+Create a new system module repository from the template:
+
 ```bash
-# Initialize in new directory
-mkdir my-server-config
-cd my-server-config
 nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system
 ```
 
-See [templates/system/README.md](../templates/system/README.md) for detailed usage.
+This creates:
+
+```
+my-system-config/
+├── flake.nix        # Optional: for testing standalone
+├── default.nix      # Your NixOS module
+└── README.md        # Documentation
+```
 
 ### User Module Template
 
+Create a new user module repository:
+
 ```bash
-# Initialize in new directory
-mkdir my-dotfiles
-cd my-dotfiles
 nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
 ```
 
-See [templates/user/README.md](../templates/user/README.md) for detailed usage.
+This creates:
 
-## Integration Details
+```
-
+my-dotfiles/
-### Detection Logic
+├── flake.nix        # Optional: for testing standalone
-
+├── user.nix         # User options + home-manager config
-The system automatically detects external modules when a device or user value is:
+├── nixos.nix        # Optional: system-level config
-- A path (`builtins.isPath`)
+└── README.md        # Documentation
-- A string starting with `/` (absolute path)
-- A derivation (`lib.isDerivation`)
-- An attrset with `outPath` attribute (result of `fetchGit`/`fetchTarball`)
-
-### System Module Integration
-
-External system modules are imported and merged into the NixOS configuration:
-
-```nix
-import externalModulePath { inherit inputs; }
 ```
 
-They can use all standard NixOS options plus `athenix.*` namespace options.
+### Testing External Modules
 
-### User Module Integration
+Test your external module locally before pushing:
 
-External user modules are loaded in two contexts:
+```bash
+# In your module repository
+cd /path/to/my-module
 
-**User options (NixOS module context):**
+# Test the Nix syntax
-```nix
+nix flake check
-import (externalPath + "/user.nix") { inherit inputs; }
-# Evaluated as NixOS module to extract athenix.users.<username> options
 ```
 
-**Home-manager configuration:**
+## Best Practices
+
+### 1. Always Pin to Specific Commits
+
+❌ Wrong - using branch names:
 ```nix
-import (externalPath + "/user.nix") { inherit inputs; }
+builtins.fetchGit {
-# Imported into home-manager for home.*, programs.*, services.* options
+  url = "https://git.factory.uga.edu/username/dotfiles";
-```
+  # No rev specified or using "main"
-
-**System-level config (optional):**
-```nix
-import (externalPath + "/nixos.nix") { inherit inputs; }
-# If present, imported as NixOS module for system-level configuration
-```
-
-### Combining External and Local Config
-
-You can mix external modules with local overrides:
-
-```nix
-nix-lxc = {
-  devices = {
-    "server" = builtins.fetchGit {
-      url = "https://git.factory.uga.edu/org/base-config";
-      rev = "abc123...";
-    };
-  };
-  overrides = {
-    # Apply to all devices, including external ones
-    athenix.users.admin.enable = true;
-    networking.firewall.allowedTCPPorts = [ 80 443 ];
-  };
-};
-```
-
-### Minimal User Module
-
-**user.nix:**
-```nix
-{ inputs, ... }:
-{ config, lib, pkgs, osConfig ? null, ... }:
-{
-  # User account options
-  athenix.users.myusername = {
-    description = "My Name";
-    shell = pkgs.zsh;
-    hashedPassword = "!";
-  };
-  
-  # Home-manager config
-  home.packages = with pkgs; [ vim git ];
 }
 ```
 
-### Full User Module with Dotfiles
+✅ Correct - using commit hash:
-
-```
-dotfiles/
-├── user.nix
-├── nixos.nix
-└── config/
-    ├── bashrc
-    ├── vimrc
-    └── gitconfig
-```
-
-**user.nix:**
 ```nix
-{ inputs, ... }:
+builtins.fetchGit {
-{ config, lib, pkgs, osConfig ? null, ... }:
+  url = "https://git.factory.uga.edu/username/dotfiles";
-{
+  rev = "abc123def456789...";
-  # User account configuration
-  athenix.users.myusername = {
-    description = "My Full Name";
-    shell = pkgs.zsh;
-    extraGroups = [ "wheel" "networkmanager" ];
-    hashedPassword = "!";
-    opensshKeys = [ "ssh-ed25519 AAAA..." ];
-    useZshTheme = true;
-    useNvimPlugins = true;
-  };
-  
-  # Home-manager configuration
-  home.packages = with pkgs; [
-    ripgrep
-    fd
-    bat
-  ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox;
-  
-  programs.git = {
-    enable = true;
-    userName = "My Full Name";
-    userEmail = "me@example.com";
-    extraConfig.init.defaultBranch = "main";
-  };
-  
-  home.file = {
-    ".bashrc".source = ./config/bashrc;
-    ".vimrc".source = ./config/vimrc;
-    ".gitconfig".source = ./config/gitconfig;
-  };
 }
 ```
 
+### 2. Keep External Modules Focused
+
+Each external module should have a clear purpose:
+- User dotfiles (one repo per user)
+- System service configuration (one repo per service/cluster)
+- Hardware-specific config (one repo per hardware setup)
+
+### 3. Document Your Modules
+
+Include a README with:
+- What the module configures
+- Required dependencies
+- Usage examples
+- Configuration options
+
+### 4. Use Semantic Versioning
+
+Tag releases in Git:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+Reference specific versions:
+
+```nix
+builtins.fetchGit {
+  url = "https://git.factory.uga.edu/org/server-config";
+  rev = "v1.0.0";  # Can use tags too
+}
+```
+
+### 5. Test Before Updating Pins
+
+When updating commit hashes:
+
+```bash
+# Test new revision locally
+nix flake update
+
+# Validate all configurations
+nix flake check --show-trace
+
+# Only commit after validation
+git add . && git commit -m "Update module versions"
+```
+
 ## See Also
 
-- [INVENTORY.md](INVENTORY.md) - Host configuration guide
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management
-- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
+- [INVENTORY.md](INVENTORY.md) - Host configuration
-- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
+- [NAMESPACE.md](NAMESPACE.md) - Configuration options
-- [templates/system/](../templates/system/) - System module template
-- [templates/user/](../templates/user/) - User module template
 - [README.md](../README.md) - Main documentation
+- [templates/user/](../templates/user/) - User module template
+- [templates/system/](../templates/system/) - System module template

docs/INVENTORY.md

@@ -1,101 +1,272 @@
 # Host Inventory Configuration
 
-This guide explains how to configure hosts in `inventory.nix` to define your fleet of devices.
+This document explains the `inventory.nix` file, which defines all hosts in your fleet.
 
 ## Table of Contents
 
-- [Understanding Inventory Structure](#understanding-inventory-structure)
+- [Overview](#overview)
-- [Hostname Generation Rules](#hostname-generation-rules)
+- [Structure](#structure)
-- [Adding Hosts](#adding-hosts)
+- [Hostname Generation](#hostname-generation)
-- [Device Configuration Options](#device-configuration-options)
+- [Configuration Methods](#configuration-methods)
+- [Options](#options)
 - [Examples](#examples)
 
-## Understanding Inventory Structure
+## Overview
 
-The `inventory.nix` file defines all hosts in the fleet using a flexible system. Top-level keys are always hostname **prefixes**, and actual hostnames are generated from device configurations.
+`inventory.nix` defines your fleet of hosts. Top-level keys are hostname **prefixes**, and actual hostnames are generated from device specifications. This allows you to manage large fleets with minimal repetition.
 
-## Hostname Generation Rules
+**Key concepts:**
+- Each top-level key generates one or more NixOS configurations
+- Host type defaults to the prefix name (can be overridden)
+- System architecture defaults to `x86_64-linux`
+- Common configuration can be applied to all devices in a group via `overrides`
 
-- **Numeric suffixes**: no dash (e.g., `nix-laptop1`, `nix-laptop2`)
+## Structure
-- **Non-numeric suffixes**: with dash (e.g., `nix-laptop-alpha`, `nix-laptop-beta`)  
-- **Custom hostnames**: Set `athenix.host.useHostPrefix = false` to use suffix as full hostname
 
-## Adding Hosts
+```nix
+{
+  "prefix-name" = {
+    # Optional: Device count or explicit device map
+    devices = 5;           # or { "1" = { ... }; "alpha" = { ... }; }
     
-### Method 1: Quick Count (Simplest)
+    # Optional: Hardware type (defaults to prefix name)
+    type = "nix-desktop";
+    
+    # Optional: System architecture
+    system = "x86_64-linux";
+    
+    # Optional: Configuration applied to ALL devices in this group
+    overrides = {
+      athenix.users.student.enable = true;
+    };
+    
+    # Optional: Per-device configuration
+    "device-suffix" = { ... };
+  };
+}
+```
+
+## Hostname Generation
+
+Hostnames are generated automatically based on the device key:
+
+- **Numeric keys** (`"1"`, `"2"`, `"42"`) → no dash: `prefix1`, `prefix2`, `prefix42`
+- **Non-numeric keys** (`"alpha"`, `"special"`) → with dash: `prefix-alpha`, `prefix-special`
+- **Custom hostnames** → Set `athenix.host.useHostPrefix = false` to use the suffix as the full hostname (no prefix)
+
+**Examples:**
 
 ```nix
 nix-laptop = {
-  devices = 5;  # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5
+  devices = 3;  # Generates: nix-laptop1, nix-laptop2, nix-laptop3
+};
+
+nix-surface = {
+  devices = {
+    "1" = { };  # → nix-surface1
+    "special" = { };  # → nix-surface-special
+  };
+};
+
+custom-machine = {
+  devices."lab-machine" = {
+    athenix.host.useHostPrefix = false;  # → lab-machine (not custom-machine-lab-machine)
+  };
 };
 ```
 
-### Method 2: Explicit Count with Overrides
+## Configuration Methods
+
+### Method 1: Simple Count
+
+Create N identical hosts:
 
 ```nix
 nix-laptop = {
   devices = 5;
-  overrides = {
-    # Applied to ALL nix-laptop hosts
-    athenix.users.student.enable = true;
-    athenix.sw.extraPackages = with pkgs; [ vim git ];
-  };
 };
+# Generates: nix-laptop1, nix-laptop2, nix-laptop3, nix-laptop4, nix-laptop5
 ```
 
-### Method 3: Individual Device Configuration
+### Method 2: Simple Count with Overrides
+
+Create N hosts with common configuration:
+
+```nix
+nix-desktop = {
+  devices = 3;
+  overrides = {
+    athenix.users.student.enable = true;
+    athenix.sw.extraPackages = with pkgs; [ vim git ];
+    services.openssh.enable = true;
+  };
+};
+# All three hosts get the overrides configuration
+```
+
+### Method 3: Explicit Device Map
+
+Configure each device individually:
 
 ```nix
 nix-surface = {
   devices = {
     "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
     "2".athenix.sw.kioskUrl = "https://dashboard2.example.com";
-    "3".athenix.sw.kioskUrl = "https://dashboard3.example.com";
+    "3" = {
+      athenix.sw.kioskUrl = "https://dashboard3.example.com";
+      services.openssh.enable = false;
+    };
   };
 };
 ```
 
-### Method 4: Mixed (Default Count + Custom Devices)
+### Method 4: External Module
+
+Reference a Git repository using the `external` field (lazy evaluation):
 
 ```nix
-nix-surface = {
+nix-lxc = {
-  defaultCount = 2;  # Creates nix-surface1, nix-surface2
+  devices."builder".external = builtins.fetchGit {
+    url = "https://git.factory.uga.edu/org/builder-config";
+    rev = "abc123...";
+  };
+};
+```
+
+### Method 5: Mixed Approach
+
+Combine default count, custom devices, and overrides:
+
+```nix
+nix-lab = {
+  defaultCount = 5;  # Creates nix-lab1 through nix-lab5
   devices = {
-    "special" = {  # Creates nix-surface-special
+    "special" = {
-      athenix.sw.kioskUrl = "https://special-dashboard.example.com";
+      athenix.sw.extraPackages = with pkgs; [ special-software ];
     };
   };
   overrides = {
-    # Applied to all devices (including "special")
+    # Applied to all devices (default count + custom)
-    athenix.sw.kioskUrl = "https://default-dashboard.example.com";
+    athenix.users.lab-admin.enable = true;
   };
 };
 ```
 
-## Device Configuration Options
+## Options
 
-### Direct Configuration (Recommended)
+### Top-Level Device Options
 
-Use any NixOS or `athenix.*` option:
+#### `devices`
+
+Specify hosts to create. Can be:
+- **Number**: Create N hosts with keys `"1"`, `"2"`, ..., `"N"`
+- **Attribute set**: Map of device names to configurations
+
+**Type**: `int | attrs`
+
+**Examples:**
+```nix
+devices = 5;  # Creates 5 hosts
+
+devices = {
+  "1" = { };
+  "alpha" = { };
+};
+```
+
+#### `defaultCount`
+
+When using a device map, also create N numbered hosts.
+
+**Type**: `int` (optional)
+
+**Example:**
+```nix
+defaultCount = 3;  # Creates "1", "2", "3" in addition to devices map
+devices = {
+  "special" = { };
+};
+# Result: hosts "1", "2", "3", and "special"
+```
+
+#### `type`
+
+Hardware type module to use. Defaults to the prefix name (inferred from top-level key).
+
+**Type**: `string` (optional)
+
+**Options**: `nix-desktop`, `nix-laptop`, `nix-surface`, `nix-lxc`, `nix-wsl`, `nix-ephemeral`
+
+**Example:**
+```nix
+lab-machines = {
+  type = "nix-desktop";  # Use desktop hardware configuration
+  devices = 5;
+};
+```
+
+#### `system`
+
+System architecture. Defaults to `x86_64-linux`.
+
+**Type**: `string` (optional)
+
+**Example:**
+```nix
+arm-devices = {
+  system = "aarch64-linux";
+  devices = 2;
+};
+```
+
+#### `overrides`
+
+Configuration applied to all devices in this group. Useful for fleet-wide settings.
+
+**Type**: `attrs` (optional)
+
+**Example:**
+```nix
+nix-laptop = {
+  devices = 10;
+  overrides = {
+    # Applied to all 10 laptops
+    athenix.users.staff.enable = true;
+    services.openssh.enable = true;
+    boot.loader.timeout = 10;
+  };
+};
+```
+
+### Per-Device Options
+
+Any NixOS or `athenix.*` option can be set per-device:
 
 ```nix
+nix-surface = {
+  devices = {
     "1" = {
-  # Athenix options
+      # athenix.* namespace options
-  athenix.users.myuser.enable = true;
+      athenix.users.student.enable = true;
-  athenix.host.filesystem.swapSize = "64G";
+      athenix.host.filesystem.device = "/dev/sda";
-  athenix.sw.extraPackages = with pkgs; [ docker ];
+      athenix.host.filesystem.swapSize = "16G";
-  athenix.sw.kioskUrl = "https://example.com";
+      athenix.sw.kioskUrl = "https://dashboard1.example.com";
+      athenix.sw.extraPackages = with pkgs; [ firefox ];
       
       # Standard NixOS options
       networking.firewall.enable = false;
       services.openssh.enable = true;
       time.timeZone = "America/New_York";
+      boot.kernelPackages = pkgs.linuxPackages_latest;
+    };
+  };
 };
 ```
 
 ### Convenience: `athenix.forUser`
 
-Quick setup for single-user systems (especially WSL):
+Quick setup for single-user systems (especially WSL). This automatically enables a user and sets the WSL default user:
 
 ```nix
 nix-wsl = {

docs/NAMESPACE.md

@@ -1,38 +1,47 @@
 # Configuration Namespace Reference
 
-All UGA Innovation Factory-specific options are under the `athenix` namespace to avoid conflicts with standard NixOS options.
+All UGA Innovation Factory-specific options are in the `athenix` namespace to avoid conflicts with standard NixOS options.
 
 ## Table of Contents
 
 - [Host Configuration (`athenix.host`)](#host-configuration-athenixhost)
 - [Software Configuration (`athenix.sw`)](#software-configuration-athenixsw)
 - [User Management (`athenix.users`)](#user-management-athenixusers)
-- [System Configuration (`athenix.system`)](#system-configuration-athenixsystem)
 - [Convenience Options](#convenience-options)
 
 ## Host Configuration (`athenix.host`)
 
-Hardware and host-specific settings.
+Hardware and boot-related settings.
 
-### `athenix.host.filesystem`
+### `athenix.host.filesystem.device`
 
-Disk and storage configuration.
+Boot disk device path.
 
-**Options:**
+**Type:** String
-- `athenix.host.filesystem.device` - Boot disk device (default: `/dev/sda`)
+
-- `athenix.host.filesystem.swapSize` - Swap file size (default: `"32G"`)
+**Default:** `"/dev/sda"`
 
 **Example:**
 ```nix
-athenix.host.filesystem = {
+athenix.host.filesystem.device = "/dev/nvme0n1";
-  device = "/dev/nvme0n1";
+```
-  swapSize = "64G";
+
-};
+### `athenix.host.filesystem.swapSize`
+
+Swap partition size.
+
+**Type:** String (size with unit, e.g., `"32G"`, `"2G"`)
+
+**Default:** `"32G"`
+
+**Example:**
+```nix
+athenix.host.filesystem.swapSize = "64G";
 ```
 
 ### `athenix.host.buildMethods`
 
-List of supported build artifact types for this host.
+Artifact types to build for this host.
 
 **Type:** List of strings
 
@@ -40,14 +49,21 @@ List of supported build artifact types for this host.
 
 **Default:** `[ "installer-iso" ]`
 
+**Description:**
+- `"installer-iso"` - Installer ISO with auto-install
+- `"iso"` - Live ISO (boot without installation)
+- `"ipxe"` - iPXE netboot artifacts
+- `"lxc"` - LXC container tarball
+- `"proxmox"` - Proxmox VMA template
+
 **Example:**
 ```nix
-athenix.host.buildMethods = [ "lxc" "proxmox" ];
+athenix.host.buildMethods = [ "installer-iso" "lxc" ];
 ```
 
 ### `athenix.host.useHostPrefix`
 
-Whether to prepend the host type prefix to the hostname (used in inventory generation).
+Whether to prepend the host type prefix to the generated hostname.
 
 **Type:** Boolean
 
@@ -55,15 +71,19 @@ Whether to prepend the host type prefix to the hostname (used in inventory gener
 
 **Example:**
 ```nix
-athenix.host.useHostPrefix = false;  # "builder" instead of "nix-lxc-builder"
+# With useHostPrefix = true (default)
+# Device "1" under "nix-laptop" → "nix-laptop1"
+
+# With useHostPrefix = false
+# Device "builder" under "nix-lxc" → "builder" (not "nix-lxc-builder")
+athenix.host.useHostPrefix = false;
 ```
 
-### `athenix.host.wsl`
+### `athenix.host.wsl.user`
 
-WSL-specific configuration options.
+Default WSL user account (only for `nix-wsl` type).
 
-**Options:**
+**Type:** String (username)
-- `athenix.host.wsl.user` - Default WSL user for this instance
 
 **Example:**
 ```nix
@@ -72,11 +92,11 @@ athenix.host.wsl.user = "myusername";
 
 ## Software Configuration (`athenix.sw`)
 
-System software and application configuration.
+System type, packages, and application configuration.
 
 ### `athenix.sw.enable`
 
-Enable the software configuration module.
+Enable software configuration.
 
 **Type:** Boolean
 
@@ -84,28 +104,32 @@ Enable the software configuration module.
 
 ### `athenix.sw.type`
 
-System type that determines the software profile.
+System profile/type. Determines which software packages and services are installed.
 
-**Type:** Enum
+**Type:** String or list of strings
 
 **Options:**
-- `"desktop"` - Full desktop environment (GNOME)
+- `"desktop"` - Full GNOME desktop environment with development tools
-- `"tablet-kiosk"` - Surface tablets with kiosk mode browser
+- `"tablet-kiosk"` - Surface tablets with Firefox kiosk browser
-- `"stateless-kiosk"` - Diskless PXE boot kiosks
+- `"stateless-kiosk"` - Diskless PXE-booted ephemeral systems
 - `"headless"` - Servers and containers without GUI
+- `"builders"` - Build servers with build dependencies
 
 **Default:** `"desktop"`
 
 **Example:**
 ```nix
-athenix.sw.type = "headless";
+athenix.sw.type = "desktop";
+
+# Multiple types supported
+athenix.sw.type = [ "desktop" "headless" ];
 ```
 
 ### `athenix.sw.kioskUrl`
 
-URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk` types).
+URL to display in kiosk browser (for `tablet-kiosk` and `stateless-kiosk` types).
 
-**Type:** String
+**Type:** String (URL)
 
 **Default:** `"https://ha.factory.uga.edu"`
 
@@ -114,12 +138,13 @@ URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk`
 athenix.sw.kioskUrl = "https://dashboard.example.com";
 ```
 
-### `athenix.sw.python`
+### `athenix.sw.python.enable`
 
-Python development tools configuration.
+Enable Python development tools (pixi, uv, etc.).
 
-**Options:**
+**Type:** Boolean
-- `athenix.sw.python.enable` - Enable Python tools (pixi, uv) (default: `true`)
+
+**Default:** `true`
 
 **Example:**
 ```nix
@@ -128,11 +153,13 @@ athenix.sw.python.enable = true;
 
 ### `athenix.sw.remoteBuild`
 
-Remote build server configuration for offloading builds.
+Configure remote build servers for offloading builds.
+
+**Type:** Attribute set
 
 **Options:**
-- `athenix.sw.remoteBuild.enable` - Use remote builders (default: enabled on tablets)
+- `enable` - Enable remote builders (Boolean, default: `true` for tablets)
-- `athenix.sw.remoteBuild.hosts` - List of build server hostnames
+- `hosts` - List of remote builder hostnames (List of strings)
 
 **Example:**
 ```nix
@@ -144,7 +171,7 @@ athenix.sw.remoteBuild = {
 
 ### `athenix.sw.extraPackages`
 
-Additional system packages to install beyond the type defaults.
+Additional system packages beyond the type defaults.
 
 **Type:** List of packages
 
@@ -154,14 +181,15 @@ Additional system packages to install beyond the type defaults.
 ```nix
 athenix.sw.extraPackages = with pkgs; [
   vim
-  htop
   docker
+  htop
+  ripgrep
 ];
 ```
 
 ### `athenix.sw.excludePackages`
 
-Packages to exclude from the default list for this system type.
+Packages to remove from the default list for this system type.
 
 **Type:** List of packages
 
@@ -170,78 +198,160 @@ Packages to exclude from the default list for this system type.
 **Example:**
 ```nix
 athenix.sw.excludePackages = with pkgs; [
-  firefox  # Remove Firefox from default desktop packages
+  firefox  # Don't install Firefox on this system
 ];
 ```
 
 ## User Management (`athenix.users`)
 
-User account configuration and management.
+User account configuration and access control.
 
 ### `athenix.users.<username>.enable`
 
-Enable a specific user account on this system.
+Enable a user account on this system.
 
 **Type:** Boolean
 
-**Default:** `false` (except `root` and `engr-ugaif` which default to `true`)
+**Default:** `false` (except `root` and `engr-ugaif` which are `true`)
 
 **Example:**
 ```nix
-athenix.users = {
+# In inventory.nix
-  myuser.enable = true;
+nix-laptop = {
-  student.enable = true;
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
 };
 ```
 
-### User Account Options
+### User Account Options (in `users.nix`)
 
-Each user in `users.nix` can be configured with:
+Define user accounts in `users.nix` with these options:
+
+#### `description`
+
+Full name or description of the user.
+
+**Type:** String
 
 ```nix
-# Option 1: Define inline in users.nix
+athenix.users.myuser.description = "John Doe";
-athenix.users.myuser = {
+```
-  description = "Full Name";
-  isNormalUser = true;                    # Default: true
-  extraGroups = [ "wheel" "docker" ];     # Additional groups
-  shell = pkgs.zsh;                       # Login shell
-  hashedPassword = "$6$...";              # Hashed password
-  opensshKeys = [ "ssh-ed25519 ..." ];    # SSH public keys
-  useZshTheme = true;                     # Use system Zsh theme
-  useNvimPlugins = true;                  # Use system Neovim config
 
-  enable = false;  # Enable per-system in inventory.nix
+#### `extraGroups`
-};
 
-# Option 2: Use external configuration (recommended)
+Additional Unix groups for the user.
-# The external user.nix can set athenix.users.myuser options directly
+
-athenix.users.anotheruser.external = builtins.fetchGit {
+**Type:** List of strings
+
+**Common groups:**
+- `"wheel"` - Sudo access
+- `"networkmanager"` - Network configuration
+- `"docker"` - Docker access
+- `"video"` - Video device access
+- `"audio"` - Audio device access
+- `"input"` - Input device access (keyboards, mice)
+
+```nix
+athenix.users.myuser.extraGroups = [ "wheel" "docker" "networkmanager" ];
+```
+
+#### `shell`
+
+Login shell for the user.
+
+**Type:** Package
+
+**Default:** `pkgs.bash`
+
+```nix
+athenix.users.myuser.shell = pkgs.zsh;
+```
+
+#### `hashedPassword`
+
+Password hash for the user.
+
+**Type:** String (SHA-512 hash)
+
+**Generation:**
+```bash
+mkpasswd -m sha-512
+```
+
+```nix
+athenix.users.myuser.hashedPassword = "$6$...";
+```
+
+#### `opensshKeys`
+
+SSH public keys for this user.
+
+**Type:** List of strings
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@host"
+  "ssh-rsa AAAA... user@other"
+];
+```
+
+#### `useZshTheme`
+
+Apply system Zsh theme configuration to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useZshTheme = true;
+```
+
+#### `useNvimPlugins`
+
+Apply system Neovim configuration to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useNvimPlugins = true;
+```
+
+#### `external`
+
+Reference external user configuration (dotfiles, home-manager).
+
+**Type:** Path or Git reference
+
+**Example:**
+```nix
+athenix.users.myuser.external = builtins.fetchGit {
   url = "https://git.factory.uga.edu/username/dotfiles";
   rev = "abc123...";
 };
 ```
 
-## System Configuration (`athenix.system`)
+See [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) for detailed external module usage.
 
-System-wide settings and services.
+### Enabling Users on Systems
 
-### `athenix.system.gc`
+Users defined in `users.nix` are **not enabled by default**. Enable them in `inventory.nix`:
 
-Automatic garbage collection configuration.
-
-**Options:**
-- `athenix.system.gc.enable` - Enable automatic garbage collection (default: `true`)
-- `athenix.system.gc.frequency` - How often to run (default: `"weekly"`)
-- `athenix.system.gc.retentionDays` - Days to keep old generations (default: `30`)
-- `athenix.system.gc.optimise` - Optimize Nix store automatically (default: `true`)
-
-**Example:**
 ```nix
-athenix.system.gc = {
+# Option 1: Enable on all devices in a group
-  enable = true;
+nix-laptop = {
-  frequency = "daily";
+  devices = 5;
-  retentionDays = 14;
+  overrides.athenix.users.student.enable = true;
-  optimise = true;
+};
+
+# Option 2: Enable on specific devices
+nix-surface = {
+  devices = {
+    "1".athenix.users.admin.enable = true;
+    "2".athenix.users.admin.enable = true;
+  };
 };
 ```
 
@@ -249,7 +359,7 @@ athenix.system.gc = {
 
 ### `athenix.forUser`
 
-Quick setup option that enables a user account in one line.
+Quick setup for single-user systems. Automatically enables a user and sets it as the default.
 
 **Type:** String (username) or null
 
@@ -257,11 +367,7 @@ Quick setup option that enables a user account in one line.
 
 **Example:**
 ```nix
-athenix.forUser = "myusername";  # Equivalent to athenix.users.myusername.enable = true
+# In inventory.nix - enables the user automatically
-```
-
-**Usage in inventory.nix:**
-```nix
 nix-wsl = {
   devices = {
     "alice".athenix.forUser = "alice-uga";
@@ -269,9 +375,17 @@ nix-wsl = {
 };
 ```
 
+Equivalent to:
+```nix
+"alice" = {
+  athenix.users.alice-uga.enable = true;
+  athenix.host.wsl.user = "alice-uga";
+};
+```
+
 ## See Also
 
-- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide
+- [INVENTORY.md](INVENTORY.md) - Host configuration examples
-- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management guide
-- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module integration
 - [README.md](../README.md) - Main documentation

docs/USER_CONFIGURATION.md

@@ -1,103 +1,585 @@
 # User Configuration Guide
 
-Complete guide to managing user accounts in nixos-systems.
+Comprehensive guide to managing user accounts in Athenix.
 
 ## Table of Contents
 
 - [Overview](#overview)
 - [Quick Start](#quick-start)
-- [User Account Options](#user-account-options)
+- [Defining Users](#defining-users)
-- [External User Configurations](#external-user-configurations)
 - [Enabling Users on Hosts](#enabling-users-on-hosts)
+- [External User Configurations](#external-user-configurations)
 - [Password Management](#password-management)
 - [SSH Keys](#ssh-keys)
+- [User Groups](#user-groups)
 - [Examples](#examples)
 
 ## Overview
 
-Users are defined in `users.nix` but are **not enabled by default** on all systems. Each system must explicitly enable users in `inventory.nix`.
+User accounts are defined in `users.nix` but are **not enabled by default**. Each host must explicitly enable users in `inventory.nix`.
 
-**Default enabled users:**
+**Always-enabled users:**
-- `root` - System administrator
+- `root` - System administrator (enable: true)
-- `engr-ugaif` - Innovation Factory default account
+- `engr-ugaif` - Innovation Factory default account (enable: true)
+
+All other users are disabled by default and must be explicitly enabled per-host.
 
 ## Quick Start
 
 ### 1. Define User in users.nix
 
 ```nix
-athenix.users = {
+athenix.users.myuser = {
-  # Option 1: Inline definition
+  description = "John Doe";
-  myuser = {
-    description = "My Full Name";
   extraGroups = [ "wheel" "networkmanager" ];
   shell = pkgs.zsh;
   hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
-    opensshKeys = [
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
-      "ssh-ed25519 AAAA... user@machine"
-    ];
-  };
-  
-  # Option 2: External configuration (recommended for personalization)
-  myuser.external = builtins.fetchGit {
-    url = "https://git.factory.uga.edu/username/dotfiles";
-    rev = "abc123...";  # Pin to specific commit
-  };
 };
 ```
 
-### 2. Enable User on Hosts
+### 2. Enable on Hosts in inventory.nix
-
-In `inventory.nix`:
 
 ```nix
 nix-laptop = {
-  devices = 2;
+  devices = 5;
-  overrides.athenix.users.myuser.enable = true;  # Enables on all nix-laptop hosts
+  overrides.athenix.users.myuser.enable = true;
-};
-
-# Or for specific devices
-nix-desktop = {
-  devices = {
-    "1".athenix.users.myuser.enable = true;
-    "2".athenix.users.otheruser.enable = true;
-  };
-};
-
-# Or use convenience option
-nix-wsl = {
-  devices."alice".athenix.forUser = "alice-user";  # Automatically enables user
 };
 ```
 
-## User Account Options
+### 3. Users can now log in
 
-Each user in `users.nix` can have the following options:
+Users defined and enabled this way are automatically created on the system.
+
+## Defining Users
+
+Define users in `users.nix` under `athenix.users`:
+
+### Inline User Definition
 
 ```nix
-username = {
+athenix.users.myuser = {
-  # === Identity ===
+  description = "My Full Name";
-  description = "Full Name";              # User's full name
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "$6$...";
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+  useZshTheme = true;
+  useNvimPlugins = true;
+};
+```
 
-  # === System Access ===
+### External User Configuration
-  isNormalUser = true;                    # Default: true (false for root)
+
-  extraGroups = [                         # Additional Unix groups
+Reference an external Git repository (recommended for personal dotfiles):
-    "wheel"                               # Sudo access
+
-    "networkmanager"                      # Network configuration
+```nix
-    "docker"                              # Docker access
+athenix.users.myuser.external = builtins.fetchGit {
-    "video"                               # Video device access
+  url = "https://git.factory.uga.edu/username/dotfiles";
-    "audio"                               # Audio device access
+  rev = "abc123...";  # Pin to specific commit
+};
+```
+
+The external repository should contain:
+- `user.nix` (required) - User account options AND home-manager configuration
+- `nixos.nix` (optional) - System-level configuration
+
+See [External User Configurations](#external-user-configurations) section below.
+
+## User Account Options
+
+### `description`
+
+Full name or description of the user.
+
+**Type:** String
+
+```nix
+athenix.users.myuser.description = "John Doe";
+```
+
+### `extraGroups`
+
+Additional Unix groups for the user. Default is empty.
+
+**Type:** List of strings
+
+**Common groups:**
+- `"wheel"` - Sudo access
+- `"networkmanager"` - Network configuration
+- `"docker"` - Docker and Podman access
+- `"video"` - Video device access (GPU, displays)
+- `"audio"` - Audio device access
+- `"input"` - Input devices (keyboards, mice)
+- `"kvm"` - KVM virtual machine access
+- `"libvirtd"` - Libvirt daemon access
+
+```nix
+athenix.users.myuser.extraGroups = [
+  "wheel"
+  "networkmanager"
+  "docker"
+  "video"
 ];
-  shell = pkgs.zsh;                       # Login shell (default: pkgs.bash)
+```
-  hashedPassword = "$6$...";              # Hashed password (see below)
 
-  # === SSH Access ===
+### `shell`
-  opensshKeys = [                         # SSH public keys
+
+Login shell for the user.
+
+**Type:** Package
+
+**Default:** `pkgs.bash`
+
+```nix
+athenix.users.myuser.shell = pkgs.zsh;
+# or
+athenix.users.myuser.shell = pkgs.fish;
+```
+
+### `hashedPassword`
+
+Password hash for the user. Use `!` to disable password login (SSH keys only).
+
+**Type:** String (SHA-512 hash)
+
+**Generation:**
+```bash
+# Generate a hashed password
+mkpasswd -m sha-512
+
+# Or interactively
+mkpasswd -m sha-512 -c
+```
+
+```nix
+athenix.users.myuser.hashedPassword = "$6$...";
+
+# Disable password login (require SSH keys)
+athenix.users.myuser.hashedPassword = "!";
+```
+
+### `opensshKeys`
+
+SSH public keys for remote access. Users without SSH keys require password login.
+
+**Type:** List of strings
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@laptop"
+  "ssh-rsa AAAA... user@desktop"
+];
+```
+
+**Getting your SSH public key:**
+```bash
+# Print your public key
+cat ~/.ssh/id_ed25519.pub
+
+# Generate a new key if needed
+ssh-keygen -t ed25519 -C "user@host"
+```
+
+### `useZshTheme`
+
+Apply system Zsh theme configuration to this user (if using Zsh as shell).
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useZshTheme = true;
+```
+
+### `useNvimPlugins`
+
+Apply system Neovim configuration and plugins to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useNvimPlugins = true;
+```
+
+## Enabling Users on Hosts
+
+Users are **not enabled by default**. Enable them in `inventory.nix`:
+
+### Enable on All Devices in a Group
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+### Enable on Specific Devices
+
+```nix
+nix-desktop = {
+  devices = {
+    "1".athenix.users.admin.enable = true;
+    "2".athenix.users.staff.enable = true;
+    "3".athenix.users.staff.enable = true;
+  };
+};
+```
+
+### Enable Multiple Users
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides = {
+    athenix.users.student.enable = true;
+    athenix.users.teacher.enable = true;
+  };
+};
+```
+
+### Using `athenix.forUser` Convenience
+
+Quick setup for single-user systems (especially WSL):
+
+```nix
+nix-wsl = {
+  devices = {
+    "alice".athenix.forUser = "alice-uga";
+    "bob".athenix.forUser = "bob-uga";
+  };
+};
+```
+
+This automatically enables the user and sets it as the default WSL user.
+
+## External User Configurations
+
+External user configurations (dotfiles) allow users to maintain their own home-manager setup in separate repositories.
+
+### Repository Structure
+
+```
+my-dotfiles/
+├── user.nix      # Required: User options + home-manager config
+├── nixos.nix     # Optional: System-level configuration
+└── config/       # Optional: Your actual dotfiles
+    ├── bashrc
+    ├── zshrc
+    ├── vimrc
+    └── ...
+```
+
+### user.nix (Required)
+
+This file must provide BOTH user account options AND home-manager configuration:
+
+```nix
+{ inputs, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
+{
+  # ========== User Account Configuration ==========
+  # These options define the user account itself
+  athenix.users.myusername = {
+    description = "My Full Name";
+    extraGroups = [ "wheel" "docker" "networkmanager" ];
+    shell = pkgs.zsh;
+    hashedPassword = "!";  # SSH keys only
+    opensshKeys = [
       "ssh-ed25519 AAAA... user@host"
-    "ssh-rsa AAAA... user@otherhost"
     ];
+    useZshTheme = true;
+    useNvimPlugins = true;
+  };
 
-  # === External Configuration ===
+  # ========== Home Manager Configuration ==========
+  # User environment, packages, and dotfiles
+  
+  home.packages = with pkgs; [
+    vim
+    ripgrep
+    fzf
+  ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox;
+
+  programs.git = {
+    enable = true;
+    userName = "My Name";
+    userEmail = "me@example.com";
+    extraConfig = {
+      init.defaultBranch = "main";
+      core.editor = "vim";
+    };
+  };
+
+  programs.zsh = {
+    enable = true;
+    initExtra = ''
+      # Your Zsh configuration
+    '';
+  };
+
+  # Manage dotfiles
+  home.file.".config/zshrc".source = ./config/zshrc;
+  home.file.".config/bashrc".source = ./config/bashrc;
+  home.file.".vimrc".source = ./config/vimrc;
+}
+```
+
+### nixos.nix (Optional)
+
+System-level configuration for this user (rarely needed):
+
+```nix
+{ inputs, ... }:
+{ config, lib, pkgs, ... }:
+{
+  # System-level configuration for this user
+  users.users.myusername.extraGroups = [ "docker" ];
+  environment.systemPackages = [ pkgs.docker ];
+}
+```
+
+### Using External User Configuration
+
+In `users.nix`:
+
+```nix
+athenix.users.myuser.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/username/dotfiles";
+  rev = "abc123...";  # Pin to specific commit
+};
+```
+
+Then enable on hosts in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+### External Module Parameters
+
+The `user.nix` module receives:
+
+- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.)
+- **`config`** - Home-manager configuration
+- **`lib`** - Nixpkgs library functions
+- **`pkgs`** - Package set
+- **`osConfig`** - OS-level configuration (read-only, can be used for conditional setup)
+
+### Creating External User Configuration
+
+Use the template:
+
+```bash
+nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
+```
+
+## Password Management
+
+### Generate Password Hash
+
+```bash
+# Interactive (won't echo)
+mkpasswd -m sha-512 -c
+
+# From string
+echo "mypassword" | mkpasswd -m sha-512 -s
+```
+
+### Disable Password Login
+
+Set `hashedPassword = "!"` and provide SSH keys:
+
+```nix
+athenix.users.myuser = {
+  description = "SSH-only user";
+  hashedPassword = "!";
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+};
+```
+
+### Update User Password on Running System
+
+```bash
+# As the user
+passwd
+
+# As root (to change another user's password)
+sudo passwd username
+```
+
+## SSH Keys
+
+### Add SSH Keys to a User
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@laptop"
+  "ssh-ed25519 BBBB... user@desktop"
+];
+```
+
+### Get Your SSH Public Key
+
+```bash
+# Display your public key
+cat ~/.ssh/id_ed25519.pub
+
+# Or for RSA
+cat ~/.ssh/id_rsa.pub
+```
+
+### Generate New SSH Key
+
+```bash
+# Ed25519 (recommended)
+ssh-keygen -t ed25519 -C "user@host"
+
+# RSA (older systems)
+ssh-keygen -t rsa -b 4096 -C "user@host"
+```
+
+## User Groups
+
+### wheel
+
+Allows passwordless sudo access.
+
+```nix
+athenix.users.myuser.extraGroups = [ "wheel" ];
+```
+
+### networkmanager
+
+Configure network connections (requires `networkmanager` to be enabled):
+
+```nix
+athenix.users.myuser.extraGroups = [ "networkmanager" ];
+```
+
+### docker
+
+Access Docker daemon (must have Docker enabled on system):
+
+```nix
+athenix.users.myuser.extraGroups = [ "docker" ];
+```
+
+### video and audio
+
+Access GPU and audio devices:
+
+```nix
+athenix.users.myuser.extraGroups = [ "video" "audio" ];
+```
+
+## Examples
+
+### Example 1: Basic Lab User
+
+```nix
+# users.nix
+athenix.users.student = {
+  description = "Student Account";
+  extraGroups = [ "networkmanager" ];
+  shell = pkgs.bash;
+  hashedPassword = "$6$...";
+  opensshKeys = [];  # Password login only
+};
+
+# inventory.nix
+nix-laptop = {
+  devices = 20;
+  overrides.athenix.users.student.enable = true;
+};
+```
+
+### Example 2: Developer with SSH Keys
+
+```nix
+# users.nix
+athenix.users.developer = {
+  description = "Developer";
+  extraGroups = [ "wheel" "docker" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "!";
+  opensshKeys = [
+    "ssh-ed25519 AAAA... dev@laptop"
+  ];
+  useZshTheme = true;
+  useNvimPlugins = true;
+};
+
+# inventory.nix
+nix-desktop = {
+  devices = 3;
+  overrides.athenix.users.developer.enable = true;
+};
+```
+
+### Example 3: WSL User with Dotfiles
+
+```nix
+# users.nix
+athenix.users.alice.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/alice/dotfiles";
+  rev = "abc123...";
+};
+
+# inventory.nix
+nix-wsl = {
+  devices = {
+    "alice".athenix.forUser = "alice-uga";
+  };
+};
+```
+
+### Example 4: Multiple Users on Single System
+
+```nix
+# users.nix
+athenix.users = {
+  admin = {
+    description = "System Administrator";
+    extraGroups = [ "wheel" ];
+    shell = pkgs.bash;
+    hashedPassword = "!";
+    opensshKeys = [ "ssh-ed25519 AAAA..." ];
+  };
+  guest = {
+    description = "Guest User";
+    extraGroups = [];
+    shell = pkgs.bash;
+    hashedPassword = "$6$...";
+  };
+};
+
+# inventory.nix
+nix-desktop = {
+  devices = {
+    "admin-station" = {
+      athenix.users.admin.enable = true;
+    };
+    "guest-station" = {
+      athenix.users.guest.enable = true;
+    };
+  };
+};
+```
+
+## See Also
+
+- [INVENTORY.md](INVENTORY.md) - Host configuration
+- [NAMESPACE.md](NAMESPACE.md) - All configuration options
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External modules in detail
+- [README.md](../README.md) - Main documentation
   external = builtins.fetchGit { ... };   # External user module (see below)
   
   # === Theme Integration ===

flake.lock

@@ -115,11 +115,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1765794845,
+        "lastModified": 1766150702,
-        "narHash": "sha256-YD5QWlGnusNbZCqR3pxG8tRxx9yUXayLZfAJRWspq2s=",
+        "narHash": "sha256-P0kM+5o+DKnB6raXgFEk3azw8Wqg5FL6wyl9jD+G5a4=",
         "owner": "nix-community",
         "repo": "disko",
-        "rev": "7194cfe5b7a3660726b0fe7296070eaef601cae9",
+        "rev": "916506443ecd0d0b4a0f4cf9d40a3c22ce39b378",
         "type": "github"
       },
       "original": {
@@ -318,11 +318,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1765979862,
+        "lastModified": 1767619900,
-        "narHash": "sha256-/r9/1KamvbHJx6I40H4HsSXnEcBAkj46ZwibhBx9kg0=",
+        "narHash": "sha256-KpoCBPvwHz3gAQtIUkohE2InRBFK3r0/FM6z5SPWfvM=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "d3135ab747fd9dac250ffb90b4a7e80634eacbe9",
+        "rev": "6bd04da47cfb48dfd15eabf08364b78ad894f5b2",
         "type": "github"
       },
       "original": {
@@ -464,11 +464,11 @@
     },
     "nixos-hardware": {
       "locked": {
-        "lastModified": 1764440730,
+        "lastModified": 1767185284,
-        "narHash": "sha256-ZlJTNLUKQRANlLDomuRWLBCH5792x+6XUJ4YdFRjtO4=",
+        "narHash": "sha256-ljDBUDpD1Cg5n3mJI81Hz5qeZAwCGxon4kQW3Ho3+6Q=",
         "owner": "NixOS",
         "repo": "nixos-hardware",
-        "rev": "9154f4569b6cdfd3c595851a6ba51bfaa472d9f3",
+        "rev": "40b1a28dce561bea34858287fbb23052c3ee63fe",
         "type": "github"
       },
       "original": {
@@ -518,11 +518,11 @@
     },
     "nixpkgs-old-kernel": {
       "locked": {
-        "lastModified": 1765687488,
+        "lastModified": 1767051569,
-        "narHash": "sha256-7YAJ6xgBAQ/Nr+7MI13Tui1ULflgAdKh63m1tfYV7+M=",
+        "narHash": "sha256-0MnuWoN+n1UYaGBIpqpPs9I9ZHW4kynits4mrnh1Pk4=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "d02bcc33948ca19b0aaa0213fe987ceec1f4ebe1",
+        "rev": "40ee5e1944bebdd128f9fbada44faefddfde29bd",
         "type": "github"
       },
       "original": {
@@ -534,11 +534,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1765838191,
+        "lastModified": 1767480499,
-        "narHash": "sha256-m5KWt1nOm76ILk/JSCxBM4MfK3rYY7Wq9/TZIIeGnT8=",
+        "narHash": "sha256-8IQQUorUGiSmFaPnLSo2+T+rjHtiNWc+OAzeHck7N48=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "c6f52ebd45e5925c188d1a20119978aa4ffd5ef6",
+        "rev": "30a3c519afcf3f99e2c6df3b359aec5692054d92",
         "type": "github"
       },
       "original": {

flake.nix

@@ -69,10 +69,10 @@
       ...
     }:
     let
-      hosts = import ./hosts { inherit inputs; };
+      fleet = import ./glue/fleet.nix { inherit inputs; };
       linuxSystem = "x86_64-linux";
       artifacts = import ./installer/artifacts.nix {
-        inherit inputs hosts self;
+        inherit inputs fleet self;
         system = linuxSystem;
       };
       forAllSystems = nixpkgs.lib.genAttrs [
@@ -86,13 +86,13 @@
       # Formatter for 'nix fmt'
       formatter = forAllSystems (system: nixpkgs.legacyPackages.${system}.nixfmt-rfc-style);
 
-      # Generate NixOS configurations from hosts/default.nix
+      # Generate NixOS configurations from fleet generator
-      nixosConfigurations = hosts.nixosConfigurations;
+      nixosConfigurations = fleet.nixosConfigurations;
 
       # Expose artifacts to all systems, but they are always built for x86_64-linux
       packages = forAllSystems (_: artifacts);
 
-      # Expose modules for external use
+      # Expose host type modules and installer modules for external use
       nixosModules = import ./installer/modules.nix { inherit inputs; };
 
       # Templates for external configurations

glue/boot.nix

@@ -0,0 +1,137 @@
+# ============================================================================
+# Boot & Storage Configuration
+# ============================================================================
+# This module defines:
+# - Disko partition layout (EFI, swap, root)
+# - Bootloader configuration (systemd-boot with Plymouth)
+# - Filesystem options (device, swap size)
+# - Build method options (used by installer/artifacts.nix)
+# - Convenience options (forUser, useHostPrefix)
+
+{ config, lib, ... }:
+
+{
+  options.athenix = {
+    host = {
+      useHostPrefix = lib.mkOption {
+        type = lib.types.bool;
+        default = true;
+        description = "Whether to prepend the host prefix to the hostname (used in inventory and hosts/default.nix).";
+      };
+      filesystem = {
+        device = lib.mkOption {
+          type = lib.types.str;
+          description = "The main disk device to use for installation.";
+        };
+        useSwap = lib.mkOption {
+          type = lib.types.bool;
+          default = true;
+          description = "Whether to create and use a swap partition.";
+        };
+        swapSize = lib.mkOption {
+          type = lib.types.str;
+          description = "The size of the swap partition.";
+        };
+      };
+    };
+  };
+
+  config = {
+    # ========== Disk Partitioning (Disko) ==========
+    disko.enableConfig = lib.mkDefault true;
+
+    disko.devices = {
+      disk.main = {
+        type = "disk";
+        device = config.athenix.host.filesystem.device;
+        content = {
+          type = "gpt";
+          partitions = {
+            # EFI System Partition
+            ESP = {
+              name = "ESP";
+              label = "BOOT";
+              size = "1G";
+              type = "EF00";
+              content = {
+                type = "filesystem";
+                format = "vfat";
+                mountpoint = "/boot";
+                mountOptions = [ "umask=0077" ];
+                extraArgs = [
+                  "-n"
+                  "BOOT"
+                ];
+              };
+            };
+
+            # Swap Partition (size configurable per host)
+            swap = lib.mkIf config.athenix.host.filesystem.useSwap {
+              name = "swap";
+              label = "swap";
+              size = config.athenix.host.filesystem.swapSize;
+              content = {
+                type = "swap";
+              };
+            };
+
+            # Root Partition (takes remaining space)
+            root = {
+              name = "root";
+              label = "root";
+              size = "100%";
+              content = {
+                type = "filesystem";
+                format = "ext4";
+                mountpoint = "/";
+                extraArgs = [
+                  "-L"
+                  "ROOT"
+                ];
+              };
+            };
+          };
+        };
+      };
+    };
+
+    # Bootloader Configuration
+    boot = {
+      loader.systemd-boot.enable = true;
+      loader.efi.canTouchEfiVariables = true;
+      plymouth.enable = true;
+
+      # Enable "Silent boot"
+      consoleLogLevel = 3;
+      initrd.verbose = false;
+
+      # Hide the OS choice for bootloaders.
+      # It's still possible to open the bootloader list by pressing any key
+      # It will just not appear on screen unless a key is pressed
+      loader.timeout = lib.mkDefault 0;
+    };
+
+    # Set your time zone.
+    time.timeZone = "America/New_York";
+
+    # Select internationalisation properties.
+    i18n.defaultLocale = "en_US.UTF-8";
+
+    i18n.extraLocaleSettings = {
+      LC_ADDRESS = "en_US.UTF-8";
+      LC_IDENTIFICATION = "en_US.UTF-8";
+      LC_MEASUREMENT = "en_US.UTF-8";
+      LC_MONETARY = "en_US.UTF-8";
+      LC_NAME = "en_US.UTF-8";
+      LC_NUMERIC = "en_US.UTF-8";
+      LC_PAPER = "en_US.UTF-8";
+      LC_TELEPHONE = "en_US.UTF-8";
+      LC_TIME = "en_US.UTF-8";
+    };
+
+    systemd.sleep.extraConfig = ''
+      SuspendState=freeze
+      HibernateDelaySec=2h
+    '';
+  };
+}

glue/common.nix

@@ -0,0 +1,99 @@
+# ============================================================================
+# Common Host Module
+# ============================================================================
+# This module contains all the common configuration shared by all host types.
+# It is automatically imported by the fleet generator for every host.
+
+{ inputs }:
+{
+  config,
+  lib,
+  ...
+}:
+{
+  imports = [
+    ./boot.nix
+    ./user-config.nix
+    ../sw
+    ../users.nix
+    inputs.home-manager.nixosModules.home-manager
+    inputs.agenix.nixosModules.default
+    inputs.disko.nixosModules.disko
+  ];
+
+  # Define garbage collection options here since they're consumed in this module
+  options.athenix = {
+    forUser = lib.mkOption {
+      type = lib.types.nullOr lib.types.str;
+      default = null;
+      description = ''
+        Convenience option to configure a host for a specific user.
+        Automatically enables the user (sets athenix.users.username.enable = true).
+        Value should be a username from athenix.users.accounts.
+      '';
+    };
+
+    system.gc = {
+      enable = lib.mkOption {
+        type = lib.types.bool;
+        default = true;
+        description = "Whether to enable automatic garbage collection.";
+      };
+      frequency = lib.mkOption {
+        type = lib.types.str;
+        default = "weekly";
+        description = "How often to run garbage collection (systemd timer format).";
+      };
+      retentionDays = lib.mkOption {
+        type = lib.types.int;
+        default = 30;
+        description = "Number of days to keep old generations before deletion.";
+      };
+      optimise = lib.mkOption {
+        type = lib.types.bool;
+        default = true;
+        description = "Whether to automatically optimize the Nix store.";
+      };
+    };
+
+    host.buildMethods = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [ "installer-iso" ];
+      description = ''
+        List of allowed build methods for this host (used by installer/artifacts.nix).
+        Supported methods:
+        - "installer-iso": Generates an auto-install ISO that installs this configuration to disk.
+        - "iso": Generates a live ISO (using nixos-generators).
+        - "ipxe": Generates iPXE netboot artifacts (kernel, initrd, script).
+        - "lxc": Generates an LXC container tarball.
+        - "proxmox": Generates a Proxmox VMA archive.
+      '';
+    };
+  };
+
+  config = lib.mkMerge [
+    # Enable forUser if specified
+    (lib.mkIf (config.athenix.forUser != null) {
+      athenix.users.${config.athenix.forUser}.enable = true;
+    })
+
+    {
+      system.stateVersion = "25.11";
+
+      nix.settings.experimental-features = [
+        "nix-command"
+        "flakes"
+      ];
+
+      # Automatic Garbage Collection
+      nix.gc = lib.mkIf config.athenix.system.gc.enable {
+        automatic = true;
+        dates = config.athenix.system.gc.frequency;
+        options = "--delete-older-than ${toString config.athenix.system.gc.retentionDays}d";
+      };
+
+      # Optimize storage
+      nix.optimise.automatic = config.athenix.system.gc.optimise;
+    }
+  ];
+}

glue/fleet.nix

@@ -1,36 +1,23 @@
 {
   inputs,
-  hosts ? import ../inventory.nix,
+  fleet ? import ../inventory.nix,
   ...
 }:
 
 # ============================================================================
-# Host Generator
+# Fleet Generator
 # ============================================================================
 # This file contains the logic to generate NixOS configurations for all hosts
 # defined in inventory.nix. It supports both hostname-based and count-based
 # configurations with flexible type associations.
-#
-# Inventory format:
-# {
-#   "my-hostname" = {
-#     type = "nix-desktop";  # Host type module to use
-#     system = "x86_64-linux";  # Optional
-#     # ... any athenix.* options or device-specific config
-#   };
-#
-#   "lab-prefix" = {
-#     type = "nix-laptop";
-#     count = 5;  # Generates lab-prefix1, lab-prefix2, ... lab-prefix5
-#     devices = {
-#       "machine-1" = { ... };  # Override for lab-prefix1
-#     };
-#   };
-# }
 
 let
   nixpkgs = inputs.nixpkgs;
   lib = nixpkgs.lib;
+
+  # Load all available host types from hosts/
+  hostTypes = import ../variants { inherit inputs; };
+
   # Helper to create a single NixOS system configuration
   mkHost =
     {
@@ -38,9 +25,28 @@ let
       system ? "x86_64-linux",
       hostType,
       configOverrides ? { },
-      externalModulePath ? null,
+      externalModuleThunk ? null,
     }:
     let
+      # Lazy evaluation: only fetch external module when building this host
+      externalModulePath =
+        if externalModuleThunk != null then
+          let
+            # Force evaluation of the thunk (fetchGit, fetchTarball, etc.)
+            fetchedPath = externalModuleThunk;
+            # Extract outPath from fetchGit/fetchTarball results
+            extractedPath =
+              if builtins.isAttrs fetchedPath && fetchedPath ? outPath then fetchedPath.outPath else fetchedPath;
+          in
+          if builtins.isPath extractedPath then
+            extractedPath + "/default.nix"
+          else if lib.isDerivation extractedPath then
+            extractedPath + "/default.nix"
+          else
+            extractedPath + "/default.nix"
+        else
+          null;
+
       # Load users.nix to find external user modules
       pkgs = nixpkgs.legacyPackages.${system};
       usersData = import ../users.nix { inherit pkgs; };
@@ -94,13 +100,10 @@ let
         }
       ) userNixosModulePaths;
 
-      # Load the host type module
+      # Get the host type module from the hostTypes attribute set
-      typeFile = ./types + "/${hostType}.nix";
       typeModule =
-        if builtins.pathExists typeFile then
+        hostTypes.${hostType}
-          import typeFile { inherit inputs; }
+          or (throw "Host type '${hostType}' not found. Available types: ${lib.concatStringsSep ", " (lib.attrNames hostTypes)}");
-        else
-          throw "Host type '${hostType}' not found in hosts/types/";
 
       # External module from fetchGit/fetchurl
       externalPathModule =
@@ -132,6 +135,7 @@ let
       allModules =
         userNixosModules
         ++ [
+          (import ./common.nix { inherit inputs; })
           typeModule
           overrideModule
           { networking.hostName = hostName; }
@@ -192,48 +196,22 @@ let
         lib.mapAttrsToList (
           deviceKey: deviceConfig:
           let
-            # Check if deviceConfig is a path/derivation (from fetchGit, fetchurl, etc.)
+            # Check if deviceConfig has an 'external' field for lazy evaluation
-            # fetchGit/fetchTarball return an attrset with outPath attribute
+            hasExternalField = builtins.isAttrs deviceConfig && deviceConfig ? external;
-            isExternalModule =
-              (builtins.isPath deviceConfig)
-              || (builtins.isString deviceConfig && lib.hasPrefix "/" deviceConfig)
-              || (lib.isDerivation deviceConfig)
-              || (builtins.isAttrs deviceConfig && deviceConfig ? outPath);
 
-            # Extract the actual path from fetchGit/fetchTarball results
+            # Extract external module thunk if present (don't evaluate yet!)
-            extractedPath =
+            externalModuleThunk = if hasExternalField then deviceConfig.external else null;
-              if builtins.isAttrs deviceConfig && deviceConfig ? outPath then
-                deviceConfig.outPath
-              else
-                deviceConfig;
 
-            # If external module, we use base config + overrides as the config
+            # Remove 'external' from config to avoid conflicts
-            # and pass the module path separately
+            cleanDeviceConfig =
-            actualConfig =
+              if hasExternalField then lib.removeAttrs deviceConfig [ "external" ] else deviceConfig;
-              if isExternalModule then (lib.recursiveUpdate baseConfig overrides) else deviceConfig;
 
-            # Merge: base config -> overrides -> device-specific config (only if not external module)
+            # Merge: base config -> overrides -> device-specific config
-            mergedConfig =
+            mergedConfig = lib.recursiveUpdate (lib.recursiveUpdate baseConfig overrides) cleanDeviceConfig;
-              if isExternalModule then
-                actualConfig
-              else
-                lib.recursiveUpdate (lib.recursiveUpdate baseConfig overrides) deviceConfig;
 
             # Check useHostPrefix from the merged config
             usePrefix = mergedConfig.athenix.host.useHostPrefix or true;
             hostName = mkHostName prefix deviceKey usePrefix;
-
-            # If external module, also add a default.nix path for import
-            externalModulePath =
-              if isExternalModule then
-                if builtins.isPath extractedPath then
-                  extractedPath + "/default.nix"
-                else if lib.isDerivation extractedPath then
-                  extractedPath + "/default.nix"
-                else
-                  extractedPath + "/default.nix"
-              else
-                null;
           in
           {
             name = hostName;
@@ -242,7 +220,7 @@ let
                 hostName
                 system
                 hostType
-                externalModulePath
+                externalModuleThunk
                 ;
               configOverrides = mergedConfig;
             };
@@ -289,7 +267,7 @@ let
           { };
     in
     lib.recursiveUpdate deviceHosts countHosts
-  ) hosts;
+  ) fleet;
 
   # Flatten the nested structure
   allHosts = lib.foldl' lib.recursiveUpdate { } (lib.attrValues processInventory);

hosts/boot.nix

@@ -1,189 +0,0 @@
-# ============================================================================
-# Boot & Storage Configuration
-# ============================================================================
-# This module defines:
-# - Disko partition layout (EFI, swap, root)
-# - Bootloader configuration (systemd-boot with Plymouth)
-# - Filesystem options (device, swap size)
-# - Build method options (ISO, iPXE, LXC, Proxmox)
-# - Garbage collection settings
-# - Convenience options (forUser, useHostPrefix)
-
-{ config, lib, ... }:
-
-{
-  options.athenix = {
-    forUser = lib.mkOption {
-      type = lib.types.nullOr lib.types.str;
-      default = null;
-      description = ''
-        Convenience option to configure a host for a specific user.
-        Automatically enables the user (sets athenix.users.username.enable = true).
-        Value should be a username from athenix.users.accounts.
-      '';
-    };
-
-    host = {
-      useHostPrefix = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to prepend the host prefix to the hostname (used in inventory).";
-      };
-      filesystem = {
-        device = lib.mkOption {
-          type = lib.types.str;
-          description = "The main disk device to use for installation.";
-        };
-        swapSize = lib.mkOption {
-          type = lib.types.str;
-          description = "The size of the swap partition.";
-        };
-      };
-      buildMethods = lib.mkOption {
-        type = lib.types.listOf lib.types.str;
-        default = [ "installer-iso" ];
-        description = ''
-          List of allowed build methods for this host.
-          Supported methods:
-          - "installer-iso": Generates an auto-install ISO that installs this configuration to disk.
-          - "iso": Generates a live ISO (using nixos-generators).
-          - "ipxe": Generates iPXE netboot artifacts (kernel, initrd, script).
-          - "lxc": Generates an LXC container tarball.
-          - "proxmox": Generates a Proxmox VMA archive.
-        '';
-      };
-    };
-
-    system.gc = {
-      enable = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to enable automatic garbage collection.";
-      };
-      frequency = lib.mkOption {
-        type = lib.types.str;
-        default = "weekly";
-        description = "How often to run garbage collection (systemd timer format).";
-      };
-      retentionDays = lib.mkOption {
-        type = lib.types.int;
-        default = 30;
-        description = "Number of days to keep old generations before deletion.";
-      };
-      optimise = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to automatically optimize the Nix store.";
-      };
-    };
-  };
-
-  config = lib.mkMerge [
-    # Enable forUser if specified
-    (lib.mkIf (config.athenix.forUser != null) {
-      athenix.users.${config.athenix.forUser}.enable = true;
-    })
-
-    # Main configuration
-    {
-      # ========== Disk Partitioning (Disko) ==========
-      disko.enableConfig = lib.mkDefault true;
-
-      disko.devices = {
-        disk.main = {
-          type = "disk";
-          device = config.athenix.host.filesystem.device;
-          content = {
-            type = "gpt";
-            partitions = {
-              # EFI System Partition
-              ESP = {
-                name = "ESP";
-                label = "BOOT";
-                size = "1G";
-                type = "EF00";
-                content = {
-                  type = "filesystem";
-                  format = "vfat";
-                  mountpoint = "/boot";
-                  mountOptions = [ "umask=0077" ];
-                  extraArgs = [
-                    "-n"
-                    "BOOT"
-                  ];
-                };
-              };
-
-              # Swap Partition (size configurable per host)
-              swap = {
-                name = "swap";
-                label = "swap";
-                size = config.athenix.host.filesystem.swapSize;
-                content = {
-                  type = "swap";
-                };
-              };
-
-              # Root Partition (takes remaining space)
-              root = {
-                name = "root";
-                label = "root";
-                size = "100%";
-                content = {
-                  type = "filesystem";
-                  format = "ext4";
-                  mountpoint = "/";
-                  extraArgs = [
-                    "-L"
-                    "ROOT"
-                  ];
-                };
-              };
-            };
-          };
-        };
-      };
-
-      # Bootloader Configuration
-      boot = {
-        loader.systemd-boot.enable = true;
-        loader.efi.canTouchEfiVariables = true;
-        plymouth.enable = true;
-
-        # Enable "Silent boot"
-        consoleLogLevel = 3;
-        initrd.verbose = false;
-
-        # Hide the OS choice for bootloaders.
-        # It's still possible to open the bootloader list by pressing any key
-        # It will just not appear on screen unless a key is pressed
-        loader.timeout = lib.mkDefault 0;
-      };
-
-      # Set your time zone.
-      time.timeZone = "America/New_York";
-
-      # Select internationalisation properties.
-      i18n.defaultLocale = "en_US.UTF-8";
-
-      i18n.extraLocaleSettings = {
-        LC_ADDRESS = "en_US.UTF-8";
-        LC_IDENTIFICATION = "en_US.UTF-8";
-        LC_MEASUREMENT = "en_US.UTF-8";
-        LC_MONETARY = "en_US.UTF-8";
-        LC_NAME = "en_US.UTF-8";
-        LC_NUMERIC = "en_US.UTF-8";
-        LC_PAPER = "en_US.UTF-8";
-        LC_TELEPHONE = "en_US.UTF-8";
-        LC_TIME = "en_US.UTF-8";
-      };
-
-      systemd.sleep.extraConfig = ''
-        SuspendState=freeze
-        HibernateDelaySec=2h
-      '';
-
-      system.stateVersion = "25.11"; # Did you read the comment?
-    }
-  ];
-}

hosts/common.nix

@@ -1,47 +0,0 @@
-# ============================================================================
-# Common Modules
-# ============================================================================
-# This module contains all the common configuration shared by all host types.
-# It includes:
-# - Boot and user configuration
-# - Software configurations
-# - User management (users.nix)
-# - Home Manager integration
-# - Secret management (agenix)
-# - Disk partitioning (disko)
-# - System-wide Nix settings (experimental features, garbage collection)
-
-{ inputs }:
-{
-  config,
-  lib,
-  ...
-}:
-{
-  imports = [
-    ./boot.nix
-    ./user-config.nix
-    ../sw
-    ../users.nix
-    inputs.home-manager.nixosModules.home-manager
-    inputs.agenix.nixosModules.default
-    inputs.disko.nixosModules.disko
-  ];
-
-  system.stateVersion = "25.11";
-
-  nix.settings.experimental-features = [
-    "nix-command"
-    "flakes"
-  ];
-
-  # Automatic Garbage Collection
-  nix.gc = lib.mkIf config.athenix.system.gc.enable {
-    automatic = true;
-    dates = config.athenix.system.gc.frequency;
-    options = "--delete-older-than ${toString config.athenix.system.gc.retentionDays}d";
-  };
-
-  # Optimize storage
-  nix.optimise.automatic = config.athenix.system.gc.optimise;
-}

installer/PROXMOX_LXC.md

@@ -46,7 +46,7 @@ Add the host to `inventory.nix` with the `nix-lxc` type or ensure it has the app
 }
 ```
 
-Your host type configuration (`hosts/types/nix-lxc.nix`) should include:
+Your host type configuration (`variants/nix-lxc.nix`) should include:
 
 ```nix
 {

installer/artifacts.nix

@@ -1,6 +1,6 @@
 {
   inputs,
-  hosts,
+  fleet,
   self,
   system,
 }:
@@ -18,7 +18,7 @@ let
     hostName:
     let
       targetConfig = self.nixosConfigurations.${hostName}.config;
-      targetSystem = targetConfig.system.build.toplevel;
+      targetSystemBuild = targetConfig.system.build;
       diskoScript = targetConfig.system.build.diskoScript;
     in
     nixpkgs.lib.nixosSystem {
@@ -27,7 +27,7 @@ let
         inherit
           inputs
           hostName
-          targetSystem
+          targetSystemBuild
           diskoScript
           ;
         hostPlatform = system;
@@ -45,7 +45,7 @@ let
     nixos-generators.nixosGenerate {
       inherit system;
       specialArgs = { inherit inputs; };
-      modules = hosts.modules.${hostName} ++ [
+      modules = fleet.modules.${hostName} ++ [
         {
           disko.enableConfig = lib.mkForce false;
           services.upower.enable = lib.mkForce false;
@@ -61,7 +61,7 @@ let
     nixpkgs.lib.nixosSystem {
       inherit system;
       specialArgs = { inherit inputs; };
-      modules = hosts.modules.${hostName} ++ [
+      modules = fleet.modules.${hostName} ++ [
         "${nixpkgs}/nixos/modules/installer/netboot/netboot.nix"
         {
           disko.enableConfig = lib.mkForce false;
@@ -70,14 +70,14 @@ let
       ];
     };
 
-  hostNames = builtins.attrNames hosts.nixosConfigurations;
+  hostNames = builtins.attrNames fleet.nixosConfigurations;
 
   # Generate installer ISOs for hosts that have "installer-iso" in their buildMethods
   installerPackages = lib.listToAttrs (
     lib.concatMap (
       name:
       let
-        cfg = hosts.nixosConfigurations.${name};
+        cfg = fleet.nixosConfigurations.${name};
       in
       if lib.elem "installer-iso" cfg.config.athenix.host.buildMethods then
         [
@@ -96,7 +96,7 @@ let
     lib.concatMap (
       name:
       let
-        cfg = hosts.nixosConfigurations.${name};
+        cfg = fleet.nixosConfigurations.${name};
       in
       if lib.elem "iso" cfg.config.athenix.host.buildMethods then
         [
@@ -115,7 +115,7 @@ let
     lib.concatMap (
       name:
       let
-        cfg = hosts.nixosConfigurations.${name};
+        cfg = fleet.nixosConfigurations.${name};
       in
       if lib.elem "ipxe" cfg.config.athenix.host.buildMethods then
         [
@@ -145,7 +145,7 @@ let
     lib.concatMap (
       name:
       let
-        cfg = hosts.nixosConfigurations.${name};
+        cfg = fleet.nixosConfigurations.${name};
       in
       if lib.elem "lxc" cfg.config.athenix.host.buildMethods then
         [
@@ -164,7 +164,7 @@ let
     lib.concatMap (
       name:
       let
-        cfg = hosts.nixosConfigurations.${name};
+        cfg = fleet.nixosConfigurations.${name};
       in
       if lib.elem "proxmox" cfg.config.athenix.host.buildMethods then
         [

installer/auto-install.nix

@@ -8,7 +8,7 @@
   inputs,
   hostName,
   hostPlatform,
-  targetSystem,
+  targetSystemBuild,
   diskoScript,
   ...
 }:
@@ -17,11 +17,21 @@
     pkgs.git
     pkgs.bashInteractive
     pkgs.curl
-    targetSystem
+    targetSystemBuild.toplevel
   ];
 
   nixpkgs.hostPlatform = hostPlatform;
 
+  nix.settings.experimental-features = "nix-command flakes";
+
+  system.extraDependencies = with targetSystemBuild; [
+    toplevel
+    etc
+    bootStage2
+  ];
+
+  isoImage.storeContents = [ targetSystemBuild.toplevel ];
+
   systemd.services.auto-install = {
     description = "Automatic NixOS install for ${hostName}";
     after = [
@@ -44,8 +54,12 @@
       echo ">>> Running disko script..."
       ${diskoScript}
 
-      echo ">>> Running nixos-install..."
+      echo ">>> Setting up NixOS..."
-      nixos-install --no-root-passwd --system ${targetSystem}
+      nixos-install \
+      --system ${targetSystemBuild.toplevel} \
+      --no-root-passwd \
+      --no-channel-copy \
+      --substituters "" 
 
       echo ">>> Done. Rebooting."
       systemctl reboot

installer/modules.nix

@@ -6,40 +6,23 @@
 #
 # Usage in another flake:
 #   # Full host type configurations (includes hardware + software + system config)
-#   inputs.nixos-systems.nixosModules.nix-desktop
+#   inputs.athenix.nixosModules.nix-desktop
-#   inputs.nixos-systems.nixosModules.nix-laptop
+#   inputs.athenix.nixosModules.nix-laptop
 #
-#   # Software-only configurations (for custom hardware setups)
+#   # Software-only configuration (for custom hardware setups)
-#   # Note: These include theme.nix in home-manager.sharedModules automatically
+#   inputs.athenix.nixosModules.sw
-#   inputs.nixos-systems.nixosModules.sw-desktop
-#   inputs.nixos-systems.nixosModules.sw-headless
-#
-#   # Home Manager modules (user-level configuration)
-#   # Theme module (no parameters):
-#   home-manager.users.myuser.imports = [ inputs.nixos-systems.homeManagerModules.theme ];
-#
-#   # Neovim module (requires user parameter):
-#   home-manager.users.myuser.imports = [
-#     (inputs.nixos-systems.homeManagerModules.nvim {
-#       user = config.athenix.users.accounts.myuser;
-#     })
-#   ];
 
 { inputs }:
-{
+# Automatically import all variant modules from variants/ directory
-  # ========== Full Host Type Modules ==========
+# This returns an attribute set like: { nix-desktop = ...; nix-laptop = ...; nix-lxc = ...; sw = ...; }
-  # Complete system configurations including hardware, boot, and software
+(import ../variants { inherit inputs; })
-  nix-desktop = import ../hosts/types/nix-desktop.nix { inherit inputs; }; # Desktop workstations
+// {
-  nix-laptop = import ../hosts/types/nix-laptop.nix { inherit inputs; }; # Laptop systems
+  # Software configuration module - main module with all athenix.sw options
-  nix-surface = import ../hosts/types/nix-surface.nix { inherit inputs; }; # Surface tablets
-  nix-lxc = import ../hosts/types/nix-lxc.nix { inherit inputs; }; # Proxmox containers
-  nix-wsl = import ../hosts/types/nix-wsl.nix { inherit inputs; }; # WSL2 systems
-  nix-ephemeral = import ../hosts/types/nix-ephemeral.nix { inherit inputs; }; # Diskless/RAM-only
-
-  # ========== Software Configuration Module ==========
-  # Main software module with all athenix.sw options
   # Use athenix.sw.type to select profile: "desktop", "tablet-kiosk", "headless", "stateless-kiosk"
-  # Use athenix.sw.extraPackages to add additional packages
+  sw =
-  # Use athenix.sw.kioskUrl to set kiosk mode URL
+    {
-  sw = { inputs, ... }@args: (import ../sw/default.nix (args // { inherit inputs; }));
+      inputs,
+      ...
+    }@args:
+    (import ../sw/default.nix (args // { inherit inputs; }));
 }

inventory.nix

@@ -1,4 +1,3 @@
-{
 # ============================================================================
 # Fleet Inventory
 # ============================================================================
@@ -44,8 +43,12 @@
 #   athenix.forUser = "username";  # Automatically enables user (sets athenix.users.username.enable = true)
 #
 # External modules (instead of config):
-  #   Device values can be either a config attrset OR a fetchGit/fetchurl call
+#   Device values can be a config attrset with an optional 'external' field:
-  #   that points to an external Nix module. The module will be imported and evaluated.
+#   devices."hostname" = {
+#     external = builtins.fetchGit { ... };  # Lazy: only fetched when building this host
+#     # ... additional config options
+#   };
+#   The external module will be imported and evaluated only when this specific host is built.
 #
 # Examples:
 #   "lab" = { devices = 3; };                           # Quick: lab1, lab2, lab3
@@ -62,11 +65,14 @@
 #     devices."alice".athenix.forUser = "alice123";       # Sets up for user alice123
 #   };
 #   "external" = {
-  #     devices."remote" = builtins.fetchGit {            # External module via Git
+#     devices."remote".external = builtins.fetchGit {     # External module via Git (lazy)
 #       url = "https://github.com/example/config";
 #       rev = "e1ccd7cc3e709afe4f50b0627e1c4bde49165014";
 #     };
-  #   };  # ========== Lab Laptops ==========
+#   };
+
+{
+  # ========== Lab Laptops ==========
   # Creates: nix-laptop1, nix-laptop2
   # Both get hdh20267 user via overrides
   nix-laptop = {
@@ -120,9 +126,9 @@
           };
         };
       };
-      "usda-dash" = builtins.fetchGit {
+      "usda-dash".external = builtins.fetchGit {
-        url = "git@factory.uga.edu:MODEL/usda-dash-config.git";
+        url = "https://git.factory.uga.edu/MODEL/usda-dash-config.git";
-        rev = "49cded91cff4a956d4e01ac6b8fe4efa86f82182";
+        rev = "dab32f5884895cead0fae28cb7d88d17951d0c12";
         submodules = true;
       };
     };
@@ -139,37 +145,11 @@
     };
   };
 
+  # ========== ZimaBoard Desktops ==========
+  # Creates: nix-zima1, nix-zima2, nix-zima3
+  nix-zima.devices = 3;
+
   # ========== Ephemeral/Netboot System ==========
   # Creates: nix-ephemeral1
   nix-ephemeral.devices = 1;
-
-  # ========== Example: External Module Configurations ==========
-  # Uncomment to use external modules from Git repositories:
-  #
-  # external-systems = {
-  #   devices = {
-  #     # Option 1: fetchGit with specific revision (recommended for reproducibility)
-  #     "prod-server" = builtins.fetchGit {
-  #       url = "https://github.com/example/server-config";
-  #       rev = "e1ccd7cc3e709afe4f50b0627e1c4bde49165014";  # Full commit hash
-  #       ref = "main";              # Optional: branch/tag name
-  #     };
-  #
-  #     # Option 2: fetchGit with latest from branch (less reproducible)
-  #     "dev-server" = builtins.fetchGit {
-  #       url = "https://github.com/example/server-config";
-  #       ref = "develop";
-  #     };
-  #
-  #     # Option 3: fetchTarball for specific release
-  #     "test-server" = builtins.fetchTarball {
-  #       url = "https://github.com/example/server-config/archive/v1.0.0.tar.gz";
-  #       sha256 = "sha256:0000000000000000000000000000000000000000000000000000";
-  #     };
-  #
-  #     # Option 4: Mix external module with local overrides
-  #     # Note: The external module's default.nix should export a NixOS module
-  #     # that accepts { inputs, ... } as parameters
-  #   };
-  # };
 }

sw/default.nix

@@ -135,6 +135,8 @@ in
           zsh # Z shell
           git # Version control
           oh-my-posh # Shell prompt theme
+          age # Simple file encryption tool
+          age-plugin-fido2-hmac # age FIDO2 support
           inputs.agenix.packages.${stdenv.hostPlatform.system}.default # Secret management
         ];
     }

sw/update-ref.nix

@@ -16,7 +16,7 @@
         update-ref [-R PATH|--athenix-repo=PATH] [-b BRANCH|--athenix-branch=BRANCH]
                   [-m "msg"|--message "msg"]
                   [-p[=false] [remote[=URL]]|--push[=false] [remote[=URL]]]
-                  [--make-local|-l] [--make-remote|-r]
+                  [--make-local|-l] [--make-remote|-r] [--ssh]
                   user=<username> | system=<device-type>:<hostkey>
       EOF
         exit 2
@@ -60,16 +60,39 @@
 
       extract_existing_fetch_url() {
         # args: mode file username key
-        python3 - "$1" "$2" "$3" "$4" <<'PY'
+        python3 - "$1" "$2" "$3" "$4" "$5"<<'PY'
       import sys, re, pathlib
-      mode, file, username, key = sys.argv[1:5]
+      mode, file, username, key, use_ssh = sys.argv[1:5]
       t = pathlib.Path(file).read_text()
 
       def url_from_block(block: str) -> str:
           if not block:
               return ""
           m = re.search(r'url\s*=\s*"([^"]+)"\s*;', block)
-          return m.group(1) if m else ""
+          url = m.group(1) if m else ""
+
+          if use_ssh = "true":
+            return url
+
+          # Already https
+          if url.startswith("https://"):
+              return url
+
+          # ssh://git@host/org/repo.git
+          m = re.match(r"ssh://(?:.+?)@([^/]+)/(.+)", url)
+          if m:
+              host, path = m.groups()
+              return f"https://{host}/{path}"
+
+          # git@host:org/repo.git
+          m = re.match(r"(?:.+?)@([^:]+):(.+)", url)
+          if m:
+              host, path = m.groups()
+              return f"https://{host}/{path}"
+
+          # If you gave me something cursed
+          raise ValueError(f"Unrecognized SSH git URL format: {url}")
+
 
       if mode == "user":
           m = re.search(r'(?s)\n\s*' + re.escape(username) + r'\.external\s*=\s*builtins\.fetchGit\s*\{(.*?)\n\s*\};', t)
@@ -154,6 +177,7 @@
 
           --make-local|-l) MODE_FORCE="local"; shift ;;
           --make-remote|-r) MODE_FORCE="remote"; shift ;;
+          --ssh) USE_SSH="true"; shift ;;
           -h|--help) usage ;;
           *) die "Unknown argument: $1" ;;
         esac
@@ -214,7 +238,7 @@
       EXISTING_URL=""
       ENTRY_EXISTS=0
       if [ "$MODE" = "user" ]; then
-        EXISTING_URL="$(extract_existing_fetch_url user "$FILE" "$USERNAME" "")"
+        EXISTING_URL="$(extract_existing_fetch_url user "$FILE" "$USERNAME" "" "false")"
         [ -n "$EXISTING_URL" ] && ENTRY_EXISTS=1 || true
       else
         FULL="$(derive_full_hostname "$DEVTYPE" "$HOSTKEY")"

sw/updater.nix

@@ -201,8 +201,10 @@ with lib;
       description = "System daemon to one-shot run the Nix updater from fleet flake as root";
       path = with pkgs; [
         git
+        openssh
         nixos-rebuild
         nix
+        coreutils
       ];
       serviceConfig = {
         Type = "oneshot";

variants/default.nix

@@ -0,0 +1,23 @@
+# ============================================================================
+# Host Types Module
+# ============================================================================
+# This module exports all available host types as an attribute set.
+# Each type is a NixOS module function that takes { inputs } and returns
+# a module configuration.
+
+{ inputs }:
+let
+  inherit (builtins) readDir attrNames;
+  lib = inputs.nixpkgs.lib;
+  inherit (lib) filterAttrs removeSuffix genAttrs;
+
+  files = readDir ./.;
+
+  # Keep only regular *.nix files except default.nix
+  nixFiles = filterAttrs (
+    name: type: type == "regular" && lib.hasSuffix ".nix" name && name != "default.nix"
+  ) files;
+
+  moduleNames = map (name: removeSuffix ".nix" name) (attrNames nixFiles);
+in
+genAttrs moduleNames (name: import ./${name}.nix { inherit inputs; })

variants/nix-desktop.nix

@@ -13,7 +13,6 @@
 }:
 {
   imports = [
-    (import ../common.nix { inherit inputs; })
     (modulesPath + "/installer/scan/not-detected.nix")
   ];
 

variants/nix-ephemeral.nix

@@ -14,7 +14,6 @@
 }:
 {
   imports = [
-    (import ../common.nix { inherit inputs; })
     (modulesPath + "/installer/scan/not-detected.nix")
   ];
 

variants/nix-laptop.nix

@@ -13,7 +13,6 @@
 }:
 {
   imports = [
-    (import ../common.nix { inherit inputs; })
     (modulesPath + "/installer/scan/not-detected.nix")
   ];
 

variants/nix-lxc.nix

@@ -13,7 +13,6 @@
 }:
 {
   imports = [
-    (import ../common.nix { inherit inputs; })
     inputs.vscode-server.nixosModules.default
     "${modulesPath}/virtualisation/proxmox-lxc.nix"
   ];

variants/nix-surface.nix

@@ -22,7 +22,6 @@ let
 in
 {
   imports = [
-    (import ../common.nix { inherit inputs; })
     (modulesPath + "/installer/scan/not-detected.nix")
     inputs.nixos-hardware.nixosModules.microsoft-surface-go
   ];

variants/nix-wsl.nix

@@ -12,7 +12,6 @@
 }:
 {
   imports = [
-    (import ../common.nix { inherit inputs; })
     inputs.nixos-wsl.nixosModules.default
     inputs.vscode-server.nixosModules.default
   ];

variants/nix-zima.nix

@@ -0,0 +1,50 @@
+# ============================================================================
+# Desktop Configuration
+# ============================================================================
+# Hardware and boot configuration for standard desktop workstations.
+# Includes Intel CPU support and NVMe storage.
+
+{ inputs, ... }:
+{
+  config,
+  lib,
+  modulesPath,
+  ...
+}:
+{
+  imports = [
+    (modulesPath + "/installer/scan/not-detected.nix")
+  ];
+
+  # ========== Boot Configuration ==========
+
+  boot.initrd.availableKernelModules = [
+    "xhci_pci" # USB 3.0 support
+    "usb_storage" # USB storage devices
+    "sd_mod" # SD card support
+    "sdhci_pci" # SD card host controller
+  ];
+  boot.initrd.kernelModules = [ ];
+  boot.kernelModules = [ "kvm-intel" ]; # Intel virtualization support
+  boot.extraModulePackages = [ ];
+  boot.kernelParams = [
+    "quiet" # Minimal boot messages
+    "splash" # Show Plymouth boot splash
+    "boot.shell_on_fail" # Emergency shell on boot failure
+    "udev.log_priority=3" # Reduce udev logging
+    "rd.systemd.show_status=auto" # Show systemd status during boot
+  ];
+
+  # ========== Filesystem Configuration ==========
+  athenix.host.filesystem.useSwap = lib.mkDefault false;
+  athenix.host.filesystem.device = lib.mkDefault "/dev/mmcblk0";
+  athenix.host.buildMethods = lib.mkDefault [ "installer-iso" ];
+  nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
+
+  # ========== Hardware Configuration ==========
+  hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
+
+  # ========== Software Profile ==========
+  athenix.sw.enable = lib.mkDefault true;
+  athenix.sw.type = lib.mkDefault "desktop";
+}