use checksum for usda-dash src copy

update
2025-12-19 23:55:17 +00:00 · 2025-12-19 23:55:17 +00:00 · 2025-12-19 23:55:17 +00:00 · 2025-12-19 23:55:17 +00:00 · 2025-12-19 23:55:17 +00:00 · 2025-12-19 23:55:17 +00:00
13 changed files with 1115 additions and 2122 deletions
@@ -1,156 +1,156 @@
-# Athenix - UGA Innovation Factory NixOS Configuration
+# UGA Innovation Factory - Athenix

 [![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)

-Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes.
+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.

-## Quick Navigation
+## Documentation

- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Define and configure hosts
- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - All `athenix.*` options reference
- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User accounts and dotfiles
- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External system and user configurations
- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs, containers, and artifacts
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflow and testing
+- **[Quick Start](#quick-start)** - Get started in 5 minutes
+- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Configure hosts and fleet inventory
+- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - Configuration options reference (`athenix.*`)
+- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User account management
+- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External configuration modules
+- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs and container images
+- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development and testing workflow

-## Getting Started
+## Quick Start

 ### For End Users

-Update your system:
+Update your system to the latest configuration:

 ```bash
 update-system
 ```

-This automatically rebuilds your system with the latest configuration from the repository.
+This command automatically fetches the latest configuration, rebuilds your system, and uses remote builders on Surface tablets to speed up builds.
+
+**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
-# Edit inventory
+# 1. Make changes to configuration files
 vim inventory.nix

-# Validate changes
+# 2. Test configuration
 nix flake check

-# Format code
+# 3. Format code
 nix fmt

-# Commit and push
-git add . && git commit -m "Your message" && git push
+# 4. Commit and push
+git add .
+git commit -m "Description of changes"
+git push
 ```

-Users automatically get changes when they run `update-system`.
+Users can now run `update-system` to get the changes.
+
+**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development workflow.**

 ## Repository Structure

 ```
-flake.nix                 # Flake entry point (inputs + outputs)
-inventory.nix             # Fleet inventory and host definitions
-users.nix                 # User account definitions
-
-flake.lock                # Locked dependency versions
-
-hosts/                    # Host generation logic
-├── default.nix           # Main host generator
-├── boot.nix              # Boot and filesystem configuration
-├── common.nix            # Common system configuration
-├── user-config.nix       # User configuration integration
-└── types/                # Hardware type modules
-    ├── nix-desktop.nix
-    ├── nix-laptop.nix
-    ├── nix-surface.nix
-    ├── nix-lxc.nix
-    ├── nix-wsl.nix
-    └── nix-ephemeral.nix
-
-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
+nixos-systems/
+├── flake.nix           # Flake entry point
+├── inventory.nix       # Fleet inventory - Define hosts here
+├── users.nix           # User accounts - Define users here
+├── hosts/              # Host generation logic
+│   ├── types/          # Hardware types (desktop, laptop, surface, lxc, wsl, ephemeral)
+│   └── ...
+├── sw/                 # Software configurations by system type
+│   ├── desktop/        # Full desktop environment
+│   ├── tablet-kiosk/   # Surface kiosk mode
+│   ├── stateless-kiosk/# Diskless PXE kiosks
+│   ├── headless/       # Servers and containers
+│   └── ...
+├── installer/          # ISO and container builds
+├── templates/          # Templates for external configs
+│   ├── system/         # System configuration template
+│   └── user/           # User configuration template
+├── docs/               # Documentation
+│   ├── INVENTORY.md    # Host configuration guide
+│   ├── NAMESPACE.md    # Option reference
+│   ├── BUILDING.md     # Building artifacts
+│   └── DEVELOPMENT.md  # Development guide
+└── assets/             # Assets (Plymouth theme, etc.)
 ```

 ## Configuration Overview

-All Innovation Factory-specific options use the `athenix` namespace to avoid conflicts with NixOS options.
+All Innovation Factory options use the `athenix.*` namespace. See **[docs/NAMESPACE.md](docs/NAMESPACE.md)** for complete reference.

-### Common Options
+**Quick examples:**

 ```nix
-# Host filesystem and hardware
-athenix.host = {
-  filesystem.device = "/dev/sda";
-  filesystem.swapSize = "32G";
-  buildMethods = [ "installer-iso" ];
-  useHostPrefix = true;
-};
+# Host configuration
+athenix.host.filesystem.device = "/dev/nvme0n1";
+athenix.host.filesystem.swapSize = "64G";

-# System type and packages
-athenix.sw = {
-  type = "desktop";  # desktop, tablet-kiosk, stateless-kiosk, headless, builders
-  extraPackages = with pkgs; [ vim docker ];
-};
+# Software configuration  
+athenix.sw.type = "desktop";  # or "headless", "tablet-kiosk"
+athenix.sw.extraPackages = with pkgs; [ vim docker ];

 # User management
 athenix.users.myuser.enable = true;
 athenix.forUser = "myuser";  # Convenience shortcut
 ```

-See [docs/NAMESPACE.md](docs/NAMESPACE.md) for complete option reference.
+## Prerequisites
+
+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 identical laptops
+# Simple: Create 5 laptops
 nix-laptop = {
-  devices = 5;
+  devices = 5;  # Creates nix-laptop1 through nix-laptop5
 };

-# With custom configuration per device
+# With configuration
 nix-surface = {
  devices = {
    "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
@@ -158,134 +158,107 @@ nix-surface = {
  };
 };

-# With common overrides
+# With overrides for all devices
 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 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.**
+**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete host configuration guide.**

 ### Using External Configurations

-Reference external repositories for user dotfiles or system configurations:
+Users and systems can reference external Git repositories for configuration:

 ```nix
-# User dotfiles (in users.nix)
-hdh20267.external = builtins.fetchGit {
-  url = "https://git.factory.uga.edu/hdh20267/dotfiles";
+# In users.nix - External dotfiles with user configuration
+myuser.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/username/dotfiles";
  rev = "abc123...";
 };
+# The external user.nix file contains both athenix.users.myuser options
+# AND home-manager configuration

-# System configuration (in inventory.nix)
+# In inventory.nix - External system config
 nix-lxc = {
-  devices."special" = builtins.fetchGit {
+  devices."server" = 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 for a specific host
-nix build .#installer-iso-nix-laptop1
+# 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 .#lxc-nix-builder

 # List all available artifacts
-nix flake show
+nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
 ```

-**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.**
+**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide on building ISOs, containers, and using remote builders.**

 ## System Types

-Set via `athenix.sw.type`:
-
 - **`desktop`** - Full GNOME desktop environment
- **`tablet-kiosk`** - Surface tablets with Firefox kiosk browser
- **`stateless-kiosk`** - Diskless PXE-booted systems
- **`headless`** - Servers and containers without GUI
- **`builders`** - Build servers
+- **`tablet-kiosk`** - Surface tablets in kiosk mode
+- **`stateless-kiosk`** - Diskless PXE boot kiosks  
+- **`headless`** - Servers and containers (no GUI)

-## Development Workflow
+Set via `athenix.sw.type` option. See [docs/NAMESPACE.md](docs/NAMESPACE.md) for all options.

+## Development
+
+**Quick commands:**
 ```bash
-# Check all configurations
-nix flake check
-
-# Format code
-nix fmt **/*.nix
-
-# Build specific artifact
-nix build .#installer-iso-nix-laptop1
-
-# Update flake inputs
-nix flake update
+nix flake check           # Validate all configurations
+nix fmt                   # Format code
+nix flake update          # Update dependencies
+nix build .#installer-iso-nix-laptop1  # Build specific artifact
 ```

-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed workflow.**
+**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development guide.**

 ## Troubleshooting

-| 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` |
+**Common issues:**

-## Prerequisites
-
-Nix with flakes support:
+- **Build errors:** Run `nix flake check --show-trace` for details
+- **External modules not loading:** Check repository access and module structure (see templates)
+- **Remote build failures:** Test SSH access: `ssh engr-ugaif@nix-builder`
+- **Out of disk space:** Run `nix-collect-garbage -d && nix store optimise`

+**Useful commands:**
 ```bash
-# Recommended: Determinate Systems installer
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-
-# Or enable flakes in existing Nix installation
-echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
+nix flake show                    # List all available outputs
+nix flake metadata                # Show flake info
+nix eval .#nixosConfigurations --apply builtins.attrNames  # List all hosts
 ```

-## More Information
+**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/BUILDING.md](docs/BUILDING.md) for detailed troubleshooting.**

- [docs/INVENTORY.md](docs/INVENTORY.md) - Host configuration
- [docs/NAMESPACE.md](docs/NAMESPACE.md) - All option references
- [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) - User management
- [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) - External modules
- [docs/BUILDING.md](docs/BUILDING.md) - Building and deployment
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - Development guide
+## Getting Help
+
+- Review documentation in `docs/` directory
+- Check templates: `templates/user/` and `templates/system/`  
+- Contact Innovation Factory IT team
@@ -1,13 +1,11 @@
-# Building Installation Media and Artifacts
+# Building Installation Media

-Guide to building installer ISOs, live images, and container artifacts.
+This guide covers building installer ISOs, live images, and container artifacts from the nixos-systems flake.

 ## 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)
@@ -17,194 +15,116 @@ Guide to building installer ISOs, live images, and container artifacts.
 ## Quick Start

 ```bash
-# List all available artifacts
-nix flake show
+# Build an installer ISO for a specific host
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1

-# Build installer ISO for a specific host
-nix build .#installer-iso-nix-laptop1
-
-# Result is in result/iso/
+# Result will be in result/iso/
 ls -lh result/iso/
 ```

 ## Available Artifacts

-Athenix can build multiple artifact types for deployment:
-
-| Type | Description | Location | Use Case |
-|------|-------------|----------|----------|
-| `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" ];
-  };
-};
-```
-
-## Building Locally
-
-Build artifacts on your local machine:
+List all available build outputs:

 ```bash
-# Build installer ISO
-nix build .#installer-iso-nix-laptop1
-
-# Build live ISO
-nix build .#iso-nix-ephemeral1
-
-# Build LXC container
-nix build .#lxc-nix-builder
-
-# Build all available outputs
-nix build .#
+nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
 ```

-**Result locations:**
- ISOs: `result/iso/nixos-*.iso`
- LXC: `result/tarball/nixos-*.tar.xz`
- Proxmox: `result/`
- iPXE: `result/` (kernel, initrd, script)
+Common artifact types:

-### Build Specific Host
-
-```bash
-# Get list of all hosts
-nix eval .#nixosConfigurations --apply builtins.attrNames
-
-# Build specific host
-nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
-```
-
-## 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
-```
+| Artifact Type | Description | Example |
+|--------------|-------------|---------|
+| `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 partition and install NixOS on first boot.
+Installer ISOs automatically install the NixOS configuration to disk on first boot.

-### Building
+### Building Locally

 ```bash
+# Build installer for a specific host
 nix build .#installer-iso-nix-laptop1
-ls -lh result/iso/
+
+# 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
 ```

-### Burning to USB
+### Building from Gitea

 ```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
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
 ```

-### Installation Process
+### Using the Installer

-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
+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:** 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" ];
-  };
-};
-```
+**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.
-
-### Building
-
-```bash
-nix build .#iso-nix-ephemeral1
-```
-
-### Usage
-
-Live ISOs are useful for:
- Testing configurations before installation
+Live ISOs boot into a temporary system without installing to disk. Useful for:
+- Testing configurations
 - Recovery operations
 - Ephemeral/stateless systems
- Booting in kiosk mode

-### Customizing Live ISO
+### Building Live ISOs

-```nix
-nix-ephemeral = {
-  devices.live = {
-    athenix.sw.type = "stateless-kiosk";
-    athenix.sw.kioskUrl = "https://dashboard.example.com";
-    athenix.host.buildMethods = [ "iso" ];
-  };
-};
+```bash
+# Build live ISO
+nix build .#iso-nix-ephemeral1
+
+# Result location
+ls -lh result/iso/nixos-*.iso
+```
+
+### Stateless Kiosk Systems
+
+For PXE netboot kiosks, use the `ipxe-*` artifacts:
+
+```bash
+# Build iPXE artifacts
+nix build .#ipxe-nix-ephemeral1
+
+# Result contains:
+# - bzImage (kernel)
+# - initrd (initial ramdisk)
+# - netboot.ipxe (iPXE script)
+ls -lh result/
 ```

 ## Container Images

 ### LXC Containers

-Build LXC container tarballs for Proxmox or standalone LXC:
+Build LXC container tarballs for Proxmox or other LXC hosts:

 ```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
-
-1. Copy tarball to Proxmox host:
+**Importing to Proxmox:**

 ```bash
+# Copy tarball to Proxmox host
 scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/
-```

-2. Create container:
-
-```bash
+# Create container from Proxmox CLI
 pct create 100 local:vztmpl/nixos-*.tar.xz \
  --hostname nix-builder \
  --memory 4096 \
@@ -212,59 +132,25 @@ pct create 100 local:vztmpl/nixos-*.tar.xz \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp
 ```

-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).
+See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed Proxmox deployment instructions.

 ### 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 Build
+### One-Time Remote Build

 ```bash
 nix build .#installer-iso-nix-laptop1 \
@@ -273,7 +159,7 @@ nix build .#installer-iso-nix-laptop1 \

 ### Persistent Configuration

-Add to `~/.config/nix/nix.conf`:
+Add to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`:

 ```conf
 builders = ssh://engr-ugaif@nix-builder x86_64-linux
@@ -285,12 +171,12 @@ Then build normally:
 nix build .#installer-iso-nix-laptop1
 ```

-### SSH Setup
+### SSH Key Setup

-Ensure SSH is configured for the builder:
+For remote builders, ensure SSH keys are configured:

 ```bash
-# Generate key if needed
+# Generate SSH key if needed
 ssh-keygen -t ed25519

 # Copy to builder
@@ -302,86 +188,77 @@ ssh engr-ugaif@nix-builder

 ### Multiple Builders

+Configure multiple build servers:
+
 ```conf
-builders = ssh://engr-ugaif@nix-builder1 x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux
+builders = ssh://engr-ugaif@nix-builder 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

-Get detailed error information:
-
+**Check configuration validity:**
 ```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
 ```

-### Build Hangs
-
+**Check space:**
 ```bash
-# List processes
-ps aux | grep nix
-
-# Cancel build
-Ctrl+C
+df -h /nix
 ```

-### Finding Artifact Outputs
+### ISO Won't Boot

+**Verify ISO integrity:**
 ```bash
-# 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
+sha256sum result/iso/nixos-*.iso
 ```

-### Build Not Creating Expected File
-
+**Check USB write:**
 ```bash
-# Check build log
-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
+# 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:**
+- UEFI systems: Try legacy BIOS mode
+- Legacy BIOS: Try UEFI mode
+
 ## 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
@@ -1,456 +1,464 @@
 # Development Guide

-Comprehensive guide for maintaining and extending Athenix.
+This guide covers development workflows for maintaining and extending the nixos-systems repository.

 ## Table of Contents

 - [Prerequisites](#prerequisites)
- [Development Workflow](#development-workflow)
 - [Testing Changes](#testing-changes)
 - [Continuous Integration](#continuous-integration)
- [Common Tasks](#common-tasks)
- [Debugging](#debugging)
- [Troubleshooting](#troubleshooting)
+- [System Rebuilds](#system-rebuilds)
+- [Updating Dependencies](#updating-dependencies)
+- [Adding Packages](#adding-packages)
+- [Python Development](#python-development)
+- [Contributing](#contributing)

 ## Prerequisites

-### Install Nix with Flakes
+Install Nix with flakes support:

 ```bash
-# Recommended: Determinate Systems installer
+# Recommended: Determinate Systems installer (includes flakes)
 curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

-# Or official installer
+# Alternative: Official installer (requires enabling flakes manually)
 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 hosts 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

-### Validate Configuration Syntax
+Always test configuration changes before committing.

-Always run before committing:
+### Validate All Configurations

 ```bash
+# Check all configurations build correctly
 nix flake check
-```

-Shows any configuration errors across all ~50+ hosts. Output:
-
-```
-checking 50 configurations...
-✓ All checks passed
+# Check with verbose error traces
+nix flake check --show-trace
 ```

 ### Test Specific Host Build

 ```bash
-# Build specific host (shows if config actually compiles)
+# Build a specific host's configuration
 nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel

-# Shorter form
-nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
+# Build installer for specific host
+nix build .#installer-iso-nix-laptop1
 ```

-### Test Installer Build
+### Test Local Changes
+
+If you're on a NixOS system managed by this flake:

 ```bash
-# 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)
+# Test changes without committing (temporary, doesn't survive reboot)
 sudo nixos-rebuild test --flake .

-# Apply and switch (persistent)
+# Apply and switch to new configuration
 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

-### CI Pipeline
+The repository uses Gitea Actions for automated testing and validation. CI jobs run on the self-hosted `nix-builder` machine.

-All pushes and pull requests trigger automated tests on the self-hosted `nix-builder`:
+### CI Workflow

-1. **Flake Check** - `nix flake check` validates all 50+ configurations
-2. **Format Check** - Verifies code formatted with `nix fmt`
-3. **Build Key Hosts** - Builds `nix-builder`, `nix-laptop1`, `nix-desktop1`
-4. **Build Artifacts** - Tests `lxc-nix-builder` and `installer-iso-nix-laptop1`
+All pull requests and pushes to main trigger the CI pipeline, which includes:
+
+1. **Flake Check** - Validates all NixOS configurations
+   - Runs `nix flake check` to ensure all systems build correctly
+   - 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

-```bash
-# Web interface
-https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions
+Check the CI status badge at the top of the README or view detailed logs:

-# Or check locally
-git log --oneline -n 5
-# Look for ✓ or ✗ next to commits
+```bash
+# View workflow status
+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions
 ```

 ### Running CI Checks Locally

-Test before pushing:
+Before pushing changes, run the same checks that CI performs:

 ```bash
-# Flake check
+# Run all checks
 nix flake check --show-trace

-# Format check
-nix fmt --check
+# Check formatting
+nix fmt
+git diff --exit-code  # Should return no changes

-# Format code
-nix fmt **/*.nix
+# Build specific configuration
+nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel

-# Build key configurations
-nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel -L
-nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
+# Build artifacts
+nix build .#lxc-nix-builder
 ```

-## Common Tasks
+### Self-Hosted Runner

-### Adding a New Host
+CI jobs run on the `nix-builder` host as a self-hosted Gitea Actions runner. This provides:

-Edit `inventory.nix`:
+- Native Nix environment without installation overhead
+- Access to local Nix store for faster builds
+- Consistent build environment matching deployment targets
+- Direct access to build caching infrastructure

-```nix
-nix-surface = {
-  devices = 3;  # Creates nix-surface1, nix-surface2, nix-surface3
-  overrides = {
-    athenix.sw.type = "tablet-kiosk";
-    athenix.sw.kioskUrl = "https://dashboard.example.com";
-  };
-};
+#### Setting Up the Gitea Actions Runner
+
+The nix-builder host is configured with a Gitea Actions self-hosted runner in `inventory.nix`. To complete the setup:
+
+1. **Generate a Gitea Runner Token**:
+   - Go to https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners
+   - 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
   ```

-Test:
+3. **Rebuild the system** to start the runner:
+   ```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
 ```

-### Modifying Software Configuration
-
-Edit appropriate file in `sw/`:
+### Update Specific Input

 ```bash
-# Desktop software
-vim sw/desktop/programs.nix
+# Update only nixpkgs
+nix flake lock --update-input nixpkgs

-# Or for all systems
-vim sw/default.nix
+# Update home-manager
+nix flake lock --update-input home-manager
+
+# Update multiple specific inputs
+nix flake lock --update-input nixpkgs --update-input home-manager
 ```

-Use `athenix.sw.extraPackages` for host-specific additions:
+### 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
+```
+
+**Tablet kiosks:**
+```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 = 5;
-  overrides.athenix.sw.extraPackages = with pkgs; [ special-tool ];
-};
-```
-
-### 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
+  devices = 2;
+  overrides = {
+    athenix.sw.extraPackages = with pkgs; [
+      vim
+      docker
+      kubernetes-helm
    ];
-}
+  };
+};
 ```

-### Using External Configurations
+### User-Specific Packages

-For user dotfiles:
+Add to user's home-manager configuration in their external `user.nix`:

 ```nix
-# users.nix
-athenix.users.myuser.external = builtins.fetchGit {
-  url = "https://git.factory.uga.edu/username/dotfiles";
-  rev = "abc123...";  # Pin to commit
-};
+# In external user.nix
+home.packages = with pkgs; [
+  ripgrep
+  fd
+  bat
+];
 ```

-For system config:
+### Search for Packages
+
+```bash
+# Search nixpkgs
+nix search nixpkgs firefox
+nix search nixpkgs python3
+
+# Show package details
+nix eval nixpkgs#firefox.meta.description
+```
+
+## Python Development
+
+All systems include modern Python tools: `pixi` and `uv`.
+
+### Pixi (Recommended for Projects)
+
+```bash
+# Initialize new project
+pixi init my-project
+cd my-project
+
+# Add dependencies
+pixi add pandas numpy matplotlib jupyter
+
+# Run Python
+pixi run python
+
+# Run Jupyter
+pixi run jupyter notebook
+
+# Run scripts
+pixi run python script.py
+
+# Shell with dependencies
+pixi shell
+```
+
+### uv (Quick Virtual Environments)
+
+```bash
+# Create virtual environment
+uv venv
+
+# Activate
+source .venv/bin/activate
+
+# Install packages
+uv pip install requests pandas
+
+# Freeze requirements
+uv pip freeze > requirements.txt
+
+# Install from requirements
+uv pip install -r requirements.txt
+```
+
+### System Python
+
+Python development tools are configured in `sw/python.nix` and can be controlled via:

 ```nix
-# inventory.nix
-nix-lxc = {
-  devices."server" = builtins.fetchGit {
-    url = "https://git.factory.uga.edu/org/server-config";
-    rev = "abc123...";
-  };
-};
+athenix.sw.python.enable = true;  # Default: enabled
 ```

-### Updating Dependencies
+## 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
-# Update all flake inputs
-nix flake update
-
-# Update specific input
-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"
+# Full workflow
+nix fmt
+nix flake check
+git add .
+git commit -m "Description of changes"
+git push
 ```

-## Debugging
+### Documentation

-### Verbose Output
+Update relevant documentation when making changes:

-Get detailed error messages:
+- `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 full error traces
-nix flake check --show-trace
+# Show all available outputs
+nix flake show

-# With maximum verbosity
-nix build .#installer-iso-nix-laptop1 -vvv
+# Evaluate specific option
+nix eval .#nixosConfigurations.nix-laptop1.config.networking.hostName

-# Show build log
-nix build .#installer-iso-nix-laptop1 -L
-```
-
-### Inspect Configuration
-
-```bash
-# Evaluate configuration for specific host
-nix eval .#nixosConfigurations.nix-laptop1.config.athenix.sw --json
-
-# Get all host names
-nix eval .#nixosConfigurations --apply builtins.attrNames
-
-# Check specific option
-nix eval .#nixosConfigurations.nix-laptop1.config.users.users
-```
-
-### Test Module Loading
-
-```bash
-# Evaluate specific module
-nix-build -A nixosConfigurations.nix-laptop1.config.system.build.toplevel
-
-# Or with flakes
-nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel --verbose
-```
-
-### Check Derivation Dependencies
-
-```bash
-# Show what dependencies a build needs
-nix show-derivation .#installer-iso-nix-laptop1
-
-# Or human-readable
-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

-# Show flake structure
-nix flake show | head -50
+# Check flake metadata
+nix flake metadata

-# Check Nix store size
-du -sh /nix/store
+# Show evaluation trace
+nix eval --show-trace .#nixosConfigurations.nix-laptop1

-# List top space users in store
-nix store du --human-readable | head -20
+# Build and enter debug shell
+nix develop

-# Find store paths for a package
-nix store path-info -rS $(which some-package)
+# Clean up old generations
+nix-collect-garbage -d
+
+# 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

- [BUILDING.md](BUILDING.md) - Building artifacts
- [INVENTORY.md](INVENTORY.md) - Host configuration
- [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
+- [INVENTORY.md](INVENTORY.md) - Host inventory configuration
+- [BUILDING.md](BUILDING.md) - Building installation media
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management
@@ -1,6 +1,6 @@
 # External Configuration Modules

-Guide to using external modules for system and user configurations.
+This guide explains how to use external modules for system and user configurations in nixos-systems.

 ## Table of Contents

@@ -8,125 +8,116 @@ Guide to using external modules for system and user configurations.
 - [System Modules](#system-modules)
 - [User Modules](#user-modules)
 - [Fetch Methods](#fetch-methods)
- [Creating External Modules](#creating-external-modules)
- [Best Practices](#best-practices)
+- [Templates](#templates)
+- [Integration Details](#integration-details)

 ## Overview

-External modules allow you to maintain configurations in separate Git repositories and reference them from Athenix.
+External modules allow you to maintain configurations in separate Git repositories and reference them from `inventory.nix` (for systems) or `users.nix` (for users).

 **Benefits:**
- **Separation** - Keep complex configs in separate repositories
- **Reproducibility** - Pin specific commits for deterministic builds
- **Reusability** - Share configurations across multiple deployments
- **Flexibility** - Mix external modules with local configuration
- **Ownership** - Users maintain their own dotfiles
+- **Separation:** Keep configs in separate repositories
+- **Versioning:** Pin to specific commits for reproducibility
+- **Reusability:** Share configurations across deployments
+- **Flexibility:** Mix external modules with local overrides

 ## System Modules

-External system modules provide host-specific NixOS configurations.
+External system modules provide complete NixOS configurations for hosts.

-### Usage
-
-In `inventory.nix`, reference an external module as a device:
+### Usage in inventory.nix

 ```nix
 nix-lxc = {
  devices = {
-    # Inline configuration
+    # Traditional inline configuration
    "local-server" = {
-      athenix.sw.type = "headless";
+      athenix.users.admin.enable = true;
      services.nginx.enable = true;
    };
    
-    # External module
+    # External module from Git
    "remote-server" = builtins.fetchGit {
      url = "https://git.factory.uga.edu/org/server-config";
-      rev = "abc123def456...";  # Must pin to specific commit
+      rev = "abc123...";  # Pin to specific commit
    };
  };
 };
 ```

-### Repository Structure
+### External Repository Structure

 ```
 server-config/
 ├── default.nix    # Required: NixOS module
-├── README.md       # Recommended: Documentation
-└── optional/
-    ├── config/     # Optional: Configuration files
-    └── scripts/    # Optional: Helper scripts
+└── README.md      # Optional: Documentation
 ```

-### Module Content (default.nix)
-
+**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 options
+  # Use athenix namespace 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 System Modules Receive
+### What External Modules Receive

- **`inputs`** - All flake inputs (nixpkgs, home-manager, disko, etc.)
- **`config`** - Current NixOS configuration (read/write)
+- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.)
+- **`config`** - Full NixOS configuration
 - **`lib`** - Nixpkgs library functions
 - **`pkgs`** - Package set

-### Configuration Order
+### Module Integration Order

-When a host is built, modules load in this order:
+When a host is built, modules are loaded in this order:

-1. Hardware type module (from `hosts/types/nix-*.nix`)
-2. Host common configuration (from `hosts/common.nix`)
-3. Software type module (from `sw/{type}/`)
-4. User NixOS modules (from `users.nix` - `nixos.nix` files)
-5. Device-specific overrides (from `inventory.nix`)
-6. External system module (if present)
+1. User NixOS modules (from `users.nix` - `nixos.nix` files)
+2. Host type module (from `hosts/types/`)
+3. Configuration overrides (from `inventory.nix`)
+4. Hostname assignment
+5. External system module (if using `builtins.fetchGit`)

-Each later module can override earlier ones using standard NixOS precedence rules.
+Later modules can override earlier ones using standard NixOS module precedence.
+
+### 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, environment setup).
+External user modules provide home-manager configurations (dotfiles, packages, programs).

-### Usage
-
-In `users.nix`, reference an external user module:
+### Usage in users.nix

 ```nix
 athenix.users = {
-  # External user module
-  myuser.external = builtins.fetchGit {
+  # External user module (dotfiles, home-manager, and user options)
+  myuser = builtins.fetchGit {
    url = "https://git.factory.uga.edu/username/dotfiles";
-    rev = "abc123def456...";  # Pin to specific commit
+    rev = "abc123...";
  };

  # Inline user definition
-  otheruser = {
-    description = "Other User";
+  inlineuser = {
+    description = "Inline User";
    extraGroups = [ "wheel" ];
    shell = pkgs.zsh;
    hashedPassword = "$6$...";
@@ -134,179 +125,148 @@ athenix.users = {
 };
 ```

-Then enable on hosts in `inventory.nix`:
+### External Repository Structure

+```
+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 = "My Full Name";
-    extraGroups = [ "wheel" "docker" ];
+    description = "Your Full Name";
    shell = pkgs.zsh;
-    hashedPassword = "!";  # SSH keys only
-    opensshKeys = [
-      "ssh-ed25519 AAAA... user@laptop"
-    ];
+    hashedPassword = "!";
+    opensshKeys = [ "ssh-ed25519 AAAA..." ];
    useZshTheme = true;
    useNvimPlugins = true;
  };

  # ========== Home Manager Configuration ==========
-  # User environment, packages, and dotfiles
-  
  # Packages
  home.packages = with pkgs; [
    vim
    git
-    ripgrep
-    fzf
+    htop
  ] ++ 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.".zshrc".source = ./config/zshrc;
-  home.file.".vimrc".source = ./config/vimrc;
-  home.file.".config/nvim".source = ./config/nvim;
-
-  # Services
-  services.gpg-agent.enable = true;
+  home.file.".bashrc".source = ./dotfiles/bashrc;
 }
 ```

-### nixos.nix (Optional)
-
-System-level configuration for this user (rarely needed):
-
+**nixos.nix (optional):**
 ```nix
 { inputs, ... }:
 { config, lib, pkgs, ... }:
 {
-  # System-level configuration
-  # Only needed if the user requires specific system-wide settings
-  
-  users.users.myusername.extraGroups = [ "docker" ];
+  # System-level configuration for this user
+  users.users.myuser.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`** - All flake inputs (nixpkgs, home-manager, etc.)
- **`config`** - Home-manager configuration (read/write)
+- **`inputs`** - Flake inputs (nixpkgs, home-manager, etc.)
+- **`config`** - Home-manager configuration
 - **`lib`** - Nixpkgs library functions
 - **`pkgs`** - Package set
- **`osConfig`** - OS configuration (read-only) - useful for conditional setup
+- **`osConfig`** - OS-level configuration (read-only)

 **In nixos.nix:**
 - **`inputs`** - Flake inputs
- **`config`** - NixOS configuration (read/write)
+- **`config`** - NixOS configuration
 - **`lib`** - Nixpkgs library functions  
 - **`pkgs`** - Package set

-### Conditional Setup Example
-
-Use `osConfig` to conditionally set up dotfiles based on the system type:
+### User Options in users.nix

 ```nix
-# In user.nix
-{ inputs, ... }:
-{ config, lib, pkgs, osConfig ? null, ... }:
-{
-  athenix.users.myuser = { /* ... */ };
+username = {
+  # Identity
+  description = "Full Name";
  
-  # Install Firefox only on desktop systems
-  home.packages = with pkgs; [
-    ripgrep
-  ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox;
+  # External configuration
+  external = builtins.fetchGit { ... };
+  # System settings
+  extraGroups = [ "wheel" "networkmanager" ];
+  hashedPassword = "$6$...";
+  opensshKeys = [ "ssh-ed25519 ..." ];
+  shell = pkgs.zsh;
  
-  # Different shell config per system
-  programs.zsh.initExtra = ''
-    ${lib.optionalString (osConfig.athenix.sw.type or null == "headless") "
-      # Headless-only settings
-    "}
-  '';
-}
+  # Theme integration
+  useZshTheme = true;      # Apply system zsh theme (default: true)
+  useNvimPlugins = true;   # Apply system nvim config (default: true)
+  
+  # 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

-### builtins.fetchGit (Recommended)
+### Recommended: fetchGit with Revision

-Pin to a specific Git revision:
+Pin to a specific commit for reproducibility:

 ```nix
 builtins.fetchGit {
-  url = "https://git.factory.uga.edu/username/dotfiles";
-  rev = "abc123def456...";  # Required: specific commit hash
+  url = "https://github.com/user/repo";
+  rev = "abc123def456...";  # Full commit hash (40 characters)
+  ref = "main";              # Optional: branch name
 }
 ```

-**Advantages:**
- Reproducible (pinned to exact commit)
- Works with any Git repository
- Supports SSH or HTTPS URLs
+**Finding the commit hash:**
+```bash
+# Latest commit on main branch
+git ls-remote https://github.com/user/repo main

-**Important:** Always specify `rev` (commit hash) for reproducibility. Don't use branches which can change.
+# Or from a local clone
+git rev-parse HEAD
+```

-### builtins.fetchTarball
+### fetchGit with Branch (Less Reproducible)
+
+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:

@@ -327,141 +287,174 @@ nix-prefetch-url --unpack https://github.com/user/repo/archive/v1.0.0.tar.gz
 Use local directories during development:

 ```nix
-# users.nix
-athenix.users.myuser.external = /home/user/my-dotfiles;
+/home/username/dev/my-config

-# inventory.nix
-nix-laptop = {
-  devices = {
-    "dev".athenix.users.myuser.enable = true;
-  };
-};
+# Or relative to repository
+./my-local-config
 ```

-**Note:** Only works if the path exists on the machine running `nix flake check` or `nix build`.
+⚠️ **Warning:** Only for testing. Use Git-based methods for production.

-## Creating External Modules
+## Templates

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

-This creates:
-
-```
-my-system-config/
-├── flake.nix        # Optional: for testing standalone
-├── default.nix      # Your NixOS module
-└── README.md        # Documentation
-```
+See [templates/system/README.md](../templates/system/README.md) for detailed usage.

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

-This creates:
+See [templates/user/README.md](../templates/user/README.md) for detailed usage.

-```
-my-dotfiles/
-├── flake.nix        # Optional: for testing standalone
-├── user.nix         # User options + home-manager config
-├── nixos.nix        # Optional: system-level config
-└── README.md        # Documentation
-```
+## Integration Details

-### Testing External Modules
+### Detection Logic

-Test your external module locally before pushing:
+The system automatically detects external modules when a device or user value is:
+- A path (`builtins.isPath`)
+- A string starting with `/` (absolute path)
+- A derivation (`lib.isDerivation`)
+- An attrset with `outPath` attribute (result of `fetchGit`/`fetchTarball`)

-```bash
-# In your module repository
-cd /path/to/my-module
+### System Module Integration

-# Test the Nix syntax
-nix flake check
-```
+External system modules are imported and merged into the NixOS configuration:

-## Best Practices
-
-### 1. Always Pin to Specific Commits
-
-❌ Wrong - using branch names:
 ```nix
-builtins.fetchGit {
-  url = "https://git.factory.uga.edu/username/dotfiles";
-  # No rev specified or using "main"
+import externalModulePath { inherit inputs; }
+```
+
+They can use all standard NixOS options plus `athenix.*` namespace options.
+
+### User Module Integration
+
+External user modules are loaded in two contexts:
+
+**User options (NixOS module context):**
+```nix
+import (externalPath + "/user.nix") { inherit inputs; }
+# Evaluated as NixOS module to extract athenix.users.<username> options
+```
+
+**Home-manager configuration:**
+```nix
+import (externalPath + "/user.nix") { inherit inputs; }
+# Imported into home-manager for home.*, programs.*, services.* options
+```
+
+**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 ];
 }
 ```

-✅ Correct - using commit hash:
+### Full User Module with Dotfiles
+
+```
+dotfiles/
+├── user.nix
+├── nixos.nix
+└── config/
+    ├── bashrc
+    ├── vimrc
+    └── gitconfig
+```
+
+**user.nix:**
 ```nix
-builtins.fetchGit {
-  url = "https://git.factory.uga.edu/username/dotfiles";
-  rev = "abc123def456789...";
+{ inputs, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
+{
+  # 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

- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management
- [INVENTORY.md](INVENTORY.md) - Host configuration
- [NAMESPACE.md](NAMESPACE.md) - Configuration options
- [README.md](../README.md) - Main documentation
- [templates/user/](../templates/user/) - User module template
+- [INVENTORY.md](INVENTORY.md) - Host configuration guide
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
+- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
 - [templates/system/](../templates/system/) - System module template
+- [templates/user/](../templates/user/) - User module template
+- [README.md](../README.md) - Main documentation
@@ -1,272 +1,101 @@
 # Host Inventory Configuration

-This document explains the `inventory.nix` file, which defines all hosts in your fleet.
+This guide explains how to configure hosts in `inventory.nix` to define your fleet of devices.

 ## Table of Contents

- [Overview](#overview)
- [Structure](#structure)
- [Hostname Generation](#hostname-generation)
- [Configuration Methods](#configuration-methods)
- [Options](#options)
+- [Understanding Inventory Structure](#understanding-inventory-structure)
+- [Hostname Generation Rules](#hostname-generation-rules)
+- [Adding Hosts](#adding-hosts)
+- [Device Configuration Options](#device-configuration-options)
 - [Examples](#examples)

-## Overview
+## Understanding Inventory Structure

-`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.
+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.

-**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`
+## Hostname Generation Rules

-## Structure
+- **Numeric suffixes**: no dash (e.g., `nix-laptop1`, `nix-laptop2`)
+- **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

-```nix
-{
-  "prefix-name" = {
-    # Optional: Device count or explicit device map
-    devices = 5;           # or { "1" = { ... }; "alpha" = { ... }; }
+## Adding Hosts

-    # 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:**
+### Method 1: Quick Count (Simplest)

 ```nix
 nix-laptop = {
-  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)
-  };
+  devices = 5;  # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5
 };
 ```

-## Configuration Methods
-
-### Method 1: Simple Count
-
-Create N identical hosts:
+### Method 2: Explicit Count with Overrides

 ```nix
 nix-laptop = {
  devices = 5;
-};
-# Generates: nix-laptop1, nix-laptop2, nix-laptop3, nix-laptop4, nix-laptop5
-```
-
-### Method 2: Simple Count with Overrides
-
-Create N hosts with common configuration:
-
-```nix
-nix-desktop = {
-  devices = 3;
  overrides = {
+    # Applied to ALL nix-laptop hosts
    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:
+### Method 3: Individual Device Configuration

 ```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";
-      services.openssh.enable = false;
-    };
-  };
-};
-```
-
-### Method 4: External Module
-
-Reference a Git repository instead of inline configuration:
-
-```nix
-nix-lxc = {
-  devices."builder" = builtins.fetchGit {
-    url = "https://git.factory.uga.edu/org/builder-config";
-    rev = "abc123...";
+    "3".athenix.sw.kioskUrl = "https://dashboard3.example.com";
  };
 };
 ```

-### Method 5: Mixed Approach
-
-Combine default count, custom devices, and overrides:
-
-```nix
-nix-lab = {
-  defaultCount = 5;  # Creates nix-lab1 through nix-lab5
-  devices = {
-    "special" = {
-      athenix.sw.extraPackages = with pkgs; [ special-software ];
-    };
-  };
-  overrides = {
-    # Applied to all devices (default count + custom)
-    athenix.users.lab-admin.enable = true;
-  };
-};
-```
-
-## Options
-
-### Top-Level Device Options
-
-#### `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:
+### Method 4: Mixed (Default Count + Custom Devices)

 ```nix
 nix-surface = {
+  defaultCount = 2;  # Creates nix-surface1, nix-surface2
  devices = {
+    "special" = {  # Creates nix-surface-special
+      athenix.sw.kioskUrl = "https://special-dashboard.example.com";
+    };
+  };
+  overrides = {
+    # Applied to all devices (including "special")
+    athenix.sw.kioskUrl = "https://default-dashboard.example.com";
+  };
+};
+```
+
+## Device Configuration Options
+
+### Direct Configuration (Recommended)
+
+Use any NixOS or `athenix.*` option:
+
+```nix
 "1" = {
-      # athenix.* namespace options
-      athenix.users.student.enable = true;
-      athenix.host.filesystem.device = "/dev/sda";
-      athenix.host.filesystem.swapSize = "16G";
-      athenix.sw.kioskUrl = "https://dashboard1.example.com";
-      athenix.sw.extraPackages = with pkgs; [ firefox ];
+  # Athenix options
+  athenix.users.myuser.enable = true;
+  athenix.host.filesystem.swapSize = "64G";
+  athenix.sw.extraPackages = with pkgs; [ docker ];
+  athenix.sw.kioskUrl = "https://example.com";
  
  # 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). This automatically enables a user and sets the WSL default user:
+Quick setup for single-user systems (especially WSL):

 ```nix
 nix-wsl = {
@@ -1,47 +1,38 @@
 # Configuration Namespace Reference

-All UGA Innovation Factory-specific options are in the `athenix` namespace to avoid conflicts with standard NixOS options.
+All UGA Innovation Factory-specific options are under 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 boot-related settings.
+Hardware and host-specific settings.

-### `athenix.host.filesystem.device`
+### `athenix.host.filesystem`

-Boot disk device path.
+Disk and storage configuration.

-**Type:** String
-
-**Default:** `"/dev/sda"`
+**Options:**
+- `athenix.host.filesystem.device` - Boot disk device (default: `/dev/sda`)
+- `athenix.host.filesystem.swapSize` - Swap file size (default: `"32G"`)

 **Example:**
 ```nix
-athenix.host.filesystem.device = "/dev/nvme0n1";
-```
-
-### `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.filesystem = {
+  device = "/dev/nvme0n1";
+  swapSize = "64G";
+};
 ```

 ### `athenix.host.buildMethods`

-Artifact types to build for this host.
+List of supported build artifact types for this host.

 **Type:** List of strings

@@ -49,21 +40,14 @@ Artifact types to build 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 = [ "installer-iso" "lxc" ];
+athenix.host.buildMethods = [ "lxc" "proxmox" ];
 ```

 ### `athenix.host.useHostPrefix`

-Whether to prepend the host type prefix to the generated hostname.
+Whether to prepend the host type prefix to the hostname (used in inventory generation).

 **Type:** Boolean

@@ -71,19 +55,15 @@ Whether to prepend the host type prefix to the generated hostname.

 **Example:**
 ```nix
-# 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.useHostPrefix = false;  # "builder" instead of "nix-lxc-builder"
 ```

-### `athenix.host.wsl.user`
+### `athenix.host.wsl`

-Default WSL user account (only for `nix-wsl` type).
+WSL-specific configuration options.

-**Type:** String (username)
+**Options:**
+- `athenix.host.wsl.user` - Default WSL user for this instance

 **Example:**
 ```nix
@@ -92,11 +72,11 @@ athenix.host.wsl.user = "myusername";

 ## Software Configuration (`athenix.sw`)

-System type, packages, and application configuration.
+System software and application configuration.

 ### `athenix.sw.enable`

-Enable software configuration.
+Enable the software configuration module.

 **Type:** Boolean

@@ -104,32 +84,28 @@ Enable software configuration.

 ### `athenix.sw.type`

-System profile/type. Determines which software packages and services are installed.
+System type that determines the software profile.

-**Type:** String or list of strings
+**Type:** Enum

 **Options:**
- `"desktop"` - Full GNOME desktop environment with development tools
- `"tablet-kiosk"` - Surface tablets with Firefox kiosk browser
- `"stateless-kiosk"` - Diskless PXE-booted ephemeral systems
+- `"desktop"` - Full desktop environment (GNOME)
+- `"tablet-kiosk"` - Surface tablets with kiosk mode browser
+- `"stateless-kiosk"` - Diskless PXE boot kiosks
 - `"headless"` - Servers and containers without GUI
- `"builders"` - Build servers with build dependencies

 **Default:** `"desktop"`

 **Example:**
 ```nix
-athenix.sw.type = "desktop";
-
-# Multiple types supported
-athenix.sw.type = [ "desktop" "headless" ];
+athenix.sw.type = "headless";
 ```

 ### `athenix.sw.kioskUrl`

-URL to display in kiosk browser (for `tablet-kiosk` and `stateless-kiosk` types).
+URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk` types).

-**Type:** String (URL)
+**Type:** String

 **Default:** `"https://ha.factory.uga.edu"`

@@ -138,13 +114,12 @@ URL to display in kiosk browser (for `tablet-kiosk` and `stateless-kiosk` types)
 athenix.sw.kioskUrl = "https://dashboard.example.com";
 ```

-### `athenix.sw.python.enable`
+### `athenix.sw.python`

-Enable Python development tools (pixi, uv, etc.).
+Python development tools configuration.

-**Type:** Boolean
-
-**Default:** `true`
+**Options:**
+- `athenix.sw.python.enable` - Enable Python tools (pixi, uv) (default: `true`)

 **Example:**
 ```nix
@@ -153,13 +128,11 @@ athenix.sw.python.enable = true;

 ### `athenix.sw.remoteBuild`

-Configure remote build servers for offloading builds.
-
-**Type:** Attribute set
+Remote build server configuration for offloading builds.

 **Options:**
- `enable` - Enable remote builders (Boolean, default: `true` for tablets)
- `hosts` - List of remote builder hostnames (List of strings)
+- `athenix.sw.remoteBuild.enable` - Use remote builders (default: enabled on tablets)
+- `athenix.sw.remoteBuild.hosts` - List of build server hostnames

 **Example:**
 ```nix
@@ -171,7 +144,7 @@ athenix.sw.remoteBuild = {

 ### `athenix.sw.extraPackages`

-Additional system packages beyond the type defaults.
+Additional system packages to install beyond the type defaults.

 **Type:** List of packages

@@ -181,15 +154,14 @@ Additional system packages beyond the type defaults.
 ```nix
 athenix.sw.extraPackages = with pkgs; [
  vim
-  docker
  htop
-  ripgrep
+  docker
 ];
 ```

 ### `athenix.sw.excludePackages`

-Packages to remove from the default list for this system type.
+Packages to exclude from the default list for this system type.

 **Type:** List of packages

@@ -198,160 +170,78 @@ Packages to remove from the default list for this system type.
 **Example:**
 ```nix
 athenix.sw.excludePackages = with pkgs; [
-  firefox  # Don't install Firefox on this system
+  firefox  # Remove Firefox from default desktop packages
 ];
 ```

 ## User Management (`athenix.users`)

-User account configuration and access control.
+User account configuration and management.

 ### `athenix.users.<username>.enable`

-Enable a user account on this system.
+Enable a specific user account on this system.

 **Type:** Boolean

-**Default:** `false` (except `root` and `engr-ugaif` which are `true`)
+**Default:** `false` (except `root` and `engr-ugaif` which default to `true`)

 **Example:**
 ```nix
-# In inventory.nix
-nix-laptop = {
-  devices = 5;
-  overrides.athenix.users.myuser.enable = true;
+athenix.users = {
+  myuser.enable = true;
+  student.enable = true;
 };
 ```

-### User Account Options (in `users.nix`)
+### User Account Options

-Define user accounts in `users.nix` with these options:
-
-#### `description`
-
-Full name or description of the user.
-
-**Type:** String
+Each user in `users.nix` can be configured with:

 ```nix
-athenix.users.myuser.description = "John Doe";
-```
+# Option 1: Define inline in users.nix
+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
  
-#### `extraGroups`
+  enable = false;  # Enable per-system in inventory.nix
+};

-Additional Unix groups for the user.
-
-**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 {
+# Option 2: Use external configuration (recommended)
+# The external user.nix can set athenix.users.myuser options directly
+athenix.users.anotheruser.external = builtins.fetchGit {
  url = "https://git.factory.uga.edu/username/dotfiles";
  rev = "abc123...";
 };
 ```

-See [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) for detailed external module usage.
+## System Configuration (`athenix.system`)

-### Enabling Users on Systems
+System-wide settings and services.

-Users defined in `users.nix` are **not enabled by default**. Enable them in `inventory.nix`:
+### `athenix.system.gc`

+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
-# Option 1: Enable on all devices in a group
-nix-laptop = {
-  devices = 5;
-  overrides.athenix.users.student.enable = true;
-};
-
-# Option 2: Enable on specific devices
-nix-surface = {
-  devices = {
-    "1".athenix.users.admin.enable = true;
-    "2".athenix.users.admin.enable = true;
-  };
+athenix.system.gc = {
+  enable = true;
+  frequency = "daily";
+  retentionDays = 14;
+  optimise = true;
 };
 ```

@@ -359,7 +249,7 @@ nix-surface = {

 ### `athenix.forUser`

-Quick setup for single-user systems. Automatically enables a user and sets it as the default.
+Quick setup option that enables a user account in one line.

 **Type:** String (username) or null

@@ -367,7 +257,11 @@ Quick setup for single-user systems. Automatically enables a user and sets it as

 **Example:**
 ```nix
-# In inventory.nix - enables the user automatically
+athenix.forUser = "myusername";  # Equivalent to athenix.users.myusername.enable = true
+```
+
+**Usage in inventory.nix:**
+```nix
 nix-wsl = {
  devices = {
    "alice".athenix.forUser = "alice-uga";
@@ -375,17 +269,9 @@ 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 configuration examples
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management guide
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module integration
+- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
 - [README.md](../README.md) - Main documentation
@@ -1,585 +1,103 @@
 # User Configuration Guide

-Comprehensive guide to managing user accounts in Athenix.
+Complete guide to managing user accounts in nixos-systems.

 ## Table of Contents

 - [Overview](#overview)
 - [Quick Start](#quick-start)
- [Defining Users](#defining-users)
- [Enabling Users on Hosts](#enabling-users-on-hosts)
+- [User Account Options](#user-account-options)
 - [External User Configurations](#external-user-configurations)
+- [Enabling Users on Hosts](#enabling-users-on-hosts)
 - [Password Management](#password-management)
 - [SSH Keys](#ssh-keys)
- [User Groups](#user-groups)
 - [Examples](#examples)

 ## Overview

-User accounts are defined in `users.nix` but are **not enabled by default**. Each host must explicitly enable users in `inventory.nix`.
+Users are defined in `users.nix` but are **not enabled by default** on all systems. Each system must explicitly enable users in `inventory.nix`.

-**Always-enabled users:**
- `root` - System administrator (enable: true)
- `engr-ugaif` - Innovation Factory default account (enable: true)
-
-All other users are disabled by default and must be explicitly enabled per-host.
+**Default enabled users:**
+- `root` - System administrator
+- `engr-ugaif` - Innovation Factory default account

 ## Quick Start

 ### 1. Define User in users.nix

 ```nix
-athenix.users.myuser = {
-  description = "John Doe";
+athenix.users = {
+  # Option 1: Inline definition
+  myuser = {
+    description = "My Full Name";
    extraGroups = [ "wheel" "networkmanager" ];
    shell = pkgs.zsh;
    hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
-  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+    opensshKeys = [
+      "ssh-ed25519 AAAA... user@machine"
+    ];
  };
-```
  
-### 2. Enable on Hosts in inventory.nix
-
-```nix
-nix-laptop = {
-  devices = 5;
-  overrides.athenix.users.myuser.enable = true;
-};
-```
-
-### 3. Users can now log in
-
-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
-athenix.users.myuser = {
-  description = "My Full Name";
-  extraGroups = [ "wheel" "networkmanager" ];
-  shell = pkgs.zsh;
-  hashedPassword = "$6$...";
-  opensshKeys = [ "ssh-ed25519 AAAA..." ];
-  useZshTheme = true;
-  useNvimPlugins = true;
-};
-```
-
-### External User Configuration
-
-Reference an external Git repository (recommended for personal dotfiles):
-
-```nix
-athenix.users.myuser.external = builtins.fetchGit {
+  # 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
  };
+};
 ```

-The external repository should contain:
- `user.nix` (required) - User account options AND home-manager configuration
- `nixos.nix` (optional) - System-level configuration
+### 2. Enable User on Hosts

-See [External User Configurations](#external-user-configurations) section below.
+In `inventory.nix`:
+
+```nix
+nix-laptop = {
+  devices = 2;
+  overrides.athenix.users.myuser.enable = true;  # Enables on all nix-laptop hosts
+};
+
+# 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

-### `description`
-
-Full name or description of the user.
-
-**Type:** String
+Each user in `users.nix` can have the following options:

 ```nix
-athenix.users.myuser.description = "John Doe";
-```
+username = {
+  # === Identity ===
+  description = "Full Name";              # User's full name
  
-### `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"
+  # === System Access ===
+  isNormalUser = true;                    # Default: true (false for root)
+  extraGroups = [                         # Additional Unix groups
+    "wheel"                               # Sudo access
+    "networkmanager"                      # Network configuration
+    "docker"                              # Docker access
+    "video"                               # Video device access
+    "audio"                               # Audio device access
  ];
-```
+  shell = pkgs.zsh;                       # Login shell (default: pkgs.bash)
+  hashedPassword = "$6$...";              # Hashed password (see below)
  
-### `shell`
-
-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 Access ===
+  opensshKeys = [                         # SSH public keys
    "ssh-ed25519 AAAA... user@host"
+    "ssh-rsa AAAA... user@otherhost"
  ];
-    useZshTheme = true;
-    useNvimPlugins = true;
-  };
  
-  # ========== 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 Configuration ===
  external = builtins.fetchGit { ... };   # External user module (see below)
  
  # === Theme Integration ===
@@ -115,11 +115,11 @@
        ]
      },
      "locked": {
-        "lastModified": 1766150702,
-        "narHash": "sha256-P0kM+5o+DKnB6raXgFEk3azw8Wqg5FL6wyl9jD+G5a4=",
+        "lastModified": 1765794845,
+        "narHash": "sha256-YD5QWlGnusNbZCqR3pxG8tRxx9yUXayLZfAJRWspq2s=",
        "owner": "nix-community",
        "repo": "disko",
-        "rev": "916506443ecd0d0b4a0f4cf9d40a3c22ce39b378",
+        "rev": "7194cfe5b7a3660726b0fe7296070eaef601cae9",
        "type": "github"
      },
      "original": {
@@ -318,11 +318,11 @@
        ]
      },
      "locked": {
-        "lastModified": 1767024057,
-        "narHash": "sha256-B1aycRjMRvb6QOGbnqDhiDzZwMebj5jxZ5qyJzaKvpI=",
+        "lastModified": 1765979862,
+        "narHash": "sha256-/r9/1KamvbHJx6I40H4HsSXnEcBAkj46ZwibhBx9kg0=",
        "owner": "nix-community",
        "repo": "home-manager",
-        "rev": "34578a2fdfce4257ce5f5baf6e7efbd4e4e252b1",
+        "rev": "d3135ab747fd9dac250ffb90b4a7e80634eacbe9",
        "type": "github"
      },
      "original": {
@@ -464,11 +464,11 @@
    },
    "nixos-hardware": {
      "locked": {
-        "lastModified": 1766568855,
-        "narHash": "sha256-UXVtN77D7pzKmzOotFTStgZBqpOcf8cO95FcupWp4Zo=",
+        "lastModified": 1764440730,
+        "narHash": "sha256-ZlJTNLUKQRANlLDomuRWLBCH5792x+6XUJ4YdFRjtO4=",
        "owner": "NixOS",
        "repo": "nixos-hardware",
-        "rev": "c5db9569ac9cc70929c268ac461f4003e3e5ca80",
+        "rev": "9154f4569b6cdfd3c595851a6ba51bfaa472d9f3",
        "type": "github"
      },
      "original": {
@@ -518,11 +518,11 @@
    },
    "nixpkgs-old-kernel": {
      "locked": {
-        "lastModified": 1766687554,
-        "narHash": "sha256-DegN7KD/EtFSKXf2jvqL6lvev6GlfAAatYBcRC8goEo=",
+        "lastModified": 1765687488,
+        "narHash": "sha256-7YAJ6xgBAQ/Nr+7MI13Tui1ULflgAdKh63m1tfYV7+M=",
        "owner": "NixOS",
        "repo": "nixpkgs",
-        "rev": "fd0ca39c92fdb4012ed8d60e1683c26fddadd136",
+        "rev": "d02bcc33948ca19b0aaa0213fe987ceec1f4ebe1",
        "type": "github"
      },
      "original": {
@@ -534,11 +534,11 @@
    },
    "nixpkgs_2": {
      "locked": {
-        "lastModified": 1766885793,
-        "narHash": "sha256-P6RVkrM9JLCW6xBjSwHfgTOQ1JwBUma5xe5LI8xAPC0=",
+        "lastModified": 1765838191,
+        "narHash": "sha256-m5KWt1nOm76ILk/JSCxBM4MfK3rYY7Wq9/TZIIeGnT8=",
        "owner": "NixOS",
        "repo": "nixpkgs",
-        "rev": "9ef261221d1e72399f2036786498d78c38185c46",
+        "rev": "c6f52ebd45e5925c188d1a20119978aa4ffd5ef6",
        "type": "github"
      },
      "original": {
@@ -34,11 +34,6 @@
          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.";
@@ -120,7 +115,7 @@
              };

              # Swap Partition (size configurable per host)
-              swap = lib.mkIf config.athenix.host.filesystem.useSwap {
+              swap = {
                name = "swap";
                label = "swap";
                size = config.athenix.host.filesystem.swapSize;
@@ -1,51 +0,0 @@
-# ============================================================================
-# Desktop Configuration
-# ============================================================================
-# Hardware and boot configuration for standard desktop workstations.
-# Includes Intel CPU support and NVMe storage.
-
-{ inputs, ... }:
-{
-  config,
-  lib,
-  modulesPath,
-  ...
-}:
-{
-  imports = [
-    (import ../common.nix { inherit inputs; })
-    (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";
-}
@@ -20,12 +20,6 @@ let
      targetConfig = self.nixosConfigurations.${hostName}.config;
      targetSystem = targetConfig.system.build.toplevel;
      diskoScript = targetConfig.system.build.diskoScript;
-      
-      # Build the closure export at build time (not runtime in ISO)
-      closureExport = pkgs.runCommand "closure-export-${hostName}" { } ''
-        mkdir -p $out
-        ${pkgs.nix}/bin/nix-store --export $(${pkgs.nix}/bin/nix-store -qR ${targetSystem}) > $out/closure.nar
-      '';
    in
    nixpkgs.lib.nixosSystem {
      inherit system;
@@ -35,7 +29,6 @@ let
          hostName
          targetSystem
          diskoScript
-          closureExport
          ;
        hostPlatform = system;
      };
@@ -1,7 +1,6 @@
 # This module defines a systemd service that automatically installs NixOS to the disk.
 # It is intended to be used in an installation ISO.
-# It expects `targetSystem` (the closure to install), `diskoScript` (the partitioning script),
-# and `closureExport` (the pre-built NAR archive) to be passed as arguments.
+# It expects `targetSystem` (the closure to install) and `diskoScript` (the partitioning script) to be passed as arguments.
 {
  config,
  lib,
@@ -11,11 +10,9 @@
  hostPlatform,
  targetSystem,
  diskoScript,
-  closureExport,
  ...
 }:
 {
-  # Ensure the entire system closure and all dependencies are included in the ISO
  environment.systemPackages = [
    pkgs.git
    pkgs.bashInteractive
@@ -23,18 +20,6 @@
    targetSystem
  ];

-  # Explicitly include the pre-built closure export and system in the ISO image
-  isoImage.contents = [
-    {
-      source = closureExport;
-      target = "/closure-export";
-    }
-    {
-      source = targetSystem;
-      target = "/system";
-    }
-  ];
-
  nixpkgs.hostPlatform = hostPlatform;

  systemd.services.auto-install = {
@@ -59,17 +44,8 @@
      echo ">>> Running disko script..."
      ${diskoScript}

-      echo ">>> Importing pre-built closure into target store..."
-      # Import the closure that was exported at build time
-      ${pkgs.nix}/bin/nix-store --store /mnt --import < /closure-export/closure.nar > /dev/null
-
      echo ">>> Running nixos-install..."
-      # Install with pre-built closure already imported (no evaluation or fetching needed)
-      ${pkgs.nix}/bin/nixos-install \
-        --no-root-passwd \
-        --root /mnt \
-        --system ${targetSystem} \
-        --option substitute false
+      nixos-install --no-root-passwd --system ${targetSystem}

      echo ">>> Done. Rebooting."
      systemctl reboot
@@ -121,8 +121,8 @@
        };
      };
      "usda-dash" = builtins.fetchGit {
-        url = "https://git.factory.uga.edu/MODEL/usda-dash-config.git";
-        rev = "dab32f5884895cead0fae28cb7d88d17951d0c12";
+        url = "git@factory.uga.edu:MODEL/usda-dash-config.git";
+        rev = "49cded91cff4a956d4e01ac6b8fe4efa86f82182";
        submodules = true;
      };
    };
@@ -139,10 +139,6 @@
    };
  };

-  # ========== ZimaBoard Desktops ==========
-  # Creates: nix-zima1, nix-zima2, nix-zima3
-  nix-zima.devices = 3;
-
  # ========== Ephemeral/Netboot System ==========
  # Creates: nix-ephemeral1
  nix-ephemeral.devices = 1;