docs: Copilot update all docs files

README.md

@@ -1,156 +1,156 @@
-# UGA Innovation Factory - Athenix
+# Athenix - UGA Innovation Factory NixOS Configuration
 
 [![CI](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions/workflows/ci.yml/badge.svg)](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions)
 
-This repository contains the NixOS configuration for the Innovation Factory's fleet of laptops, desktops, Surface tablets, and containers. It provides a declarative, reproducible system configuration using Nix flakes.
+Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes.
 
-## Documentation
+## Quick Navigation
 
-- **[Quick Start](#quick-start)** - Get started in 5 minutes
-- **[docs/INVENTORY.md](docs/INVENTORY.md)** - 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
+- **[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
+## Getting Started
 
 ### For End Users
 
-Update your system to the latest configuration:
+Update your system:
 
 ```bash
 update-system
 ```
 
-This command automatically fetches the latest configuration, rebuilds your system, and uses remote builders on Surface tablets to speed up builds.
-
-**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
-```
+This automatically rebuilds your system with the latest configuration from the repository.
 
 ### For Administrators
 
+Make configuration changes:
+
 ```bash
-# 1. Make changes to configuration files
+# Edit inventory
 vim inventory.nix
 
-# 2. Test configuration
+# Validate changes
 nix flake check
 
-# 3. Format code
+# Format code
 nix fmt
 
-# 4. Commit and push
-git add .
-git commit -m "Description of changes"
-git push
+# Commit and push
+git add . && git commit -m "Your message" && git push
 ```
 
-Users can now run `update-system` to get the changes.
-
-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development workflow.**
+Users automatically get changes when they run `update-system`.
 
 ## Repository Structure
 
 ```
-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.)
+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
 ```
 
 ## Configuration Overview
 
-All Innovation Factory options use the `athenix.*` namespace. See **[docs/NAMESPACE.md](docs/NAMESPACE.md)** for complete reference.
+All Innovation Factory-specific options use the `athenix` namespace to avoid conflicts with NixOS options.
 
-**Quick examples:**
+### Common Options
 
 ```nix
-# Host configuration
-athenix.host.filesystem.device = "/dev/nvme0n1";
-athenix.host.filesystem.swapSize = "64G";
+# Host filesystem and hardware
+athenix.host = {
+  filesystem.device = "/dev/sda";
+  filesystem.swapSize = "32G";
+  buildMethods = [ "installer-iso" ];
+  useHostPrefix = true;
+};
 
-# Software configuration  
-athenix.sw.type = "desktop";  # or "headless", "tablet-kiosk"
-athenix.sw.extraPackages = with pkgs; [ vim docker ];
+# System type and packages
+athenix.sw = {
+  type = "desktop";  # desktop, tablet-kiosk, stateless-kiosk, headless, builders
+  extraPackages = with pkgs; [ vim docker ];
+};
 
 # User management
 athenix.users.myuser.enable = true;
 athenix.forUser = "myuser";  # Convenience shortcut
 ```
 
-## Prerequisites
-
-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
-```
+See [docs/NAMESPACE.md](docs/NAMESPACE.md) for complete option reference.
 
 ## Common Tasks
 
-### Adding a New User
-
-1. Edit `users.nix`:
-
-```nix
-myuser = {
-  description = "My Full Name";
-  extraGroups = [ "wheel" "networkmanager" ];
-  shell = pkgs.zsh;
-  hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
-  opensshKeys = [ "ssh-ed25519 AAAA... user@host" ];
-};
-```
-
-2. Enable on hosts in `inventory.nix`:
-
-```nix
-nix-laptop = {
-  devices = 2;
-  overrides.athenix.users.myuser.enable = true;
-};
-```
-
-**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete user management guide.**
-
 ### Adding Hosts
 
 Edit `inventory.nix`:
 
 ```nix
-# Simple: Create 5 laptops
+# Simple: Create 5 identical laptops
 nix-laptop = {
-  devices = 5;  # Creates nix-laptop1 through nix-laptop5
+  devices = 5;
 };
 
-# With configuration
+# With custom configuration per device
 nix-surface = {
   devices = {
     "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
@@ -158,107 +158,134 @@ nix-surface = {
   };
 };
 
-# With overrides for all devices
+# With common overrides
 nix-desktop = {
   devices = 3;
   overrides = {
     athenix.users.student.enable = true;
-    athenix.sw.extraPackages = with pkgs; [ vim ];
   };
 };
 ```
 
-**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete host configuration guide.**
+**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete guide.**
+
+### Managing Users
+
+Edit `users.nix`:
+
+```nix
+athenix.users.myuser = {
+  description = "My Name";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "$6$...";  # mkpasswd -m sha-512
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+};
+```
+
+Enable in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete guide.**
 
 ### Using External Configurations
 
-Users and systems can reference external Git repositories for configuration:
+Reference external repositories for user dotfiles or system configurations:
 
 ```nix
-# In users.nix - External dotfiles with user configuration
-myuser.external = builtins.fetchGit {
-  url = "https://git.factory.uga.edu/username/dotfiles";
+# User dotfiles (in users.nix)
+hdh20267.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/hdh20267/dotfiles";
   rev = "abc123...";
 };
-# The external user.nix file contains both athenix.users.myuser options
-# AND home-manager configuration
 
-# In inventory.nix - External system config
+# System configuration (in inventory.nix)
 nix-lxc = {
-  devices."server" = builtins.fetchGit {
+  devices."special" = builtins.fetchGit {
     url = "https://git.factory.uga.edu/org/server-config";
     rev = "abc123...";
   };
 };
 ```
 
-**Create templates:**
-```bash
-# User configuration (dotfiles)
-nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
-
-# System configuration
-nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system
-```
-
 **See [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) for complete guide.**
 
 ### Building Installation Media
 
 ```bash
-# Build installer ISO
-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
 
 # Build LXC container
 nix build .#lxc-nix-builder
 
 # List all available artifacts
-nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
+nix flake show
 ```
 
-**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide on building ISOs, containers, and using remote builders.**
+**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.**
 
 ## System Types
 
+Set via `athenix.sw.type`:
+
 - **`desktop`** - Full GNOME desktop environment
-- **`tablet-kiosk`** - Surface tablets in kiosk mode
-- **`stateless-kiosk`** - Diskless PXE boot kiosks  
-- **`headless`** - Servers and containers (no GUI)
+- **`tablet-kiosk`** - Surface tablets with Firefox kiosk browser
+- **`stateless-kiosk`** - Diskless PXE-booted systems
+- **`headless`** - Servers and containers without GUI
+- **`builders`** - Build servers
 
-Set via `athenix.sw.type` option. See [docs/NAMESPACE.md](docs/NAMESPACE.md) for all options.
+## Development Workflow
 
-## Development
-
-**Quick commands:**
 ```bash
-nix flake check           # Validate all configurations
-nix fmt                   # Format code
-nix flake update          # Update dependencies
-nix build .#installer-iso-nix-laptop1  # Build specific artifact
+# 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
 ```
 
-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development guide.**
+**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed workflow.**
 
 ## Troubleshooting
 
-**Common issues:**
+| Issue | Solution |
+|-------|----------|
+| Build errors | Run `nix flake check --show-trace` for details |
+| Configuration validation | `nix flake check` checks all 50+ hosts |
+| External modules fail | Verify Git URL accessibility and module structure |
+| Remote build issues | Test SSH: `ssh engr-ugaif@nix-builder` |
+| List all hosts | `nix eval .#nixosConfigurations --apply builtins.attrNames` |
+| Disk space | `nix-collect-garbage -d && nix store optimise` |
 
-- **Build errors:** Run `nix flake check --show-trace` for details
-- **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`
+## Prerequisites
+
+Nix with flakes support:
 
-**Useful commands:**
 ```bash
-nix flake show                    # List all available outputs
-nix flake metadata                # Show flake info
-nix eval .#nixosConfigurations --apply builtins.attrNames  # List all hosts
+# 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
 ```
 
-**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/BUILDING.md](docs/BUILDING.md) for detailed troubleshooting.**
+## More Information
 
-## Getting Help
-
-- Review documentation in `docs/` directory
-- Check templates: `templates/user/` and `templates/system/`  
-- Contact Innovation Factory IT team
+- [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

docs/BUILDING.md

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

docs/DEVELOPMENT.md

@@ -1,464 +1,456 @@
 # Development Guide
 
-This guide covers development workflows for maintaining and extending the nixos-systems repository.
+Comprehensive guide for maintaining and extending Athenix.
 
 ## Table of Contents
 
 - [Prerequisites](#prerequisites)
+- [Development Workflow](#development-workflow)
 - [Testing Changes](#testing-changes)
 - [Continuous Integration](#continuous-integration)
-- [System Rebuilds](#system-rebuilds)
-- [Updating Dependencies](#updating-dependencies)
-- [Adding Packages](#adding-packages)
-- [Python Development](#python-development)
-- [Contributing](#contributing)
+- [Common Tasks](#common-tasks)
+- [Debugging](#debugging)
+- [Troubleshooting](#troubleshooting)
 
 ## Prerequisites
 
-Install Nix with flakes support:
+### Install Nix with Flakes
 
 ```bash
-# Recommended: Determinate Systems installer (includes flakes)
+# Recommended: Determinate Systems installer
 curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
 
-# Alternative: Official installer (requires enabling flakes manually)
+# Or official installer
 sh <(curl -L https://nixos.org/nix/install) --daemon
+
+# Enable flakes in existing installation
+mkdir -p ~/.config/nix
+echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
+```
+
+### Clone Repository
+
+```bash
+git clone https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
+cd athenix
+
+# Optional: enable direnv for automatic Nix environment
+direnv allow
+```
+
+## Development Workflow
+
+### Making Changes
+
+1. **Edit configuration files** - Modify `inventory.nix`, `users.nix`, or host/software config
+
+2. **Validate** - Check syntax and configuration
+
+```bash
+nix flake check
+```
+
+3. **Format code** - Apply consistent formatting
+
+```bash
+nix fmt
+```
+
+4. **Test** - Build specific artifacts or configurations
+
+```bash
+# Test specific host
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
+
+# Or build an artifact
+nix build .#installer-iso-nix-laptop1
+```
+
+5. **Commit and push**
+
+```bash
+git add .
+git commit -m "Brief description of changes"
+git push
+```
+
+### Example: Adding a New User
+
+1. Define user in `users.nix`:
+
+```nix
+athenix.users.newuser = {
+  description = "New User";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "...";  # mkpasswd -m sha-512
+};
+```
+
+2. Enable on 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
 
-Always test configuration changes before committing.
+### Validate Configuration Syntax
 
-### Validate All Configurations
+Always run before committing:
 
 ```bash
-# Check all configurations build correctly
 nix flake check
+```
 
-# Check with verbose error traces
-nix flake check --show-trace
+Shows any configuration errors across all ~50+ hosts. Output:
+
+```
+checking 50 configurations...
+✓ All checks passed
 ```
 
 ### Test Specific Host Build
 
 ```bash
-# Build a specific host's configuration
+# Build specific host (shows if config actually compiles)
 nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
 
-# Build installer for specific host
-nix build .#installer-iso-nix-laptop1
+# Shorter form
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
 ```
 
-### Test Local Changes
-
-If you're on a NixOS system managed by this flake:
+### Test Installer Build
 
 ```bash
-# Test changes without committing (temporary, doesn't survive reboot)
+# Test that installer ISO builds
+nix build .#installer-iso-nix-laptop1 -L
+```
+
+### Test on Running NixOS System
+
+If you're on a NixOS system managed by Athenix:
+
+```bash
+# Test changes temporarily (won't survive reboot)
 sudo nixos-rebuild test --flake .
 
-# Apply and switch to new configuration
+# Apply and switch (persistent)
 sudo nixos-rebuild switch --flake .
 
 # Build without switching
 sudo nixos-rebuild build --flake .
+
+# Show what will change
+sudo nixos-rebuild dry-activate --flake .
+```
+
+### Rollback
+
+If a build breaks your system:
+
+```bash
+# List recent generations
+nix-env --list-generations
+
+# Rollback to previous generation
+nix-env --rollback
+
+# Or switch to specific generation
+nix-env --switch-generation 42
 ```
 
 ## Continuous Integration
 
-The repository uses Gitea Actions for automated testing and validation. CI jobs run on the self-hosted `nix-builder` machine.
+### CI Pipeline
 
-### CI Workflow
+All pushes and pull requests trigger automated tests on the self-hosted `nix-builder`:
 
-All pull requests and pushes to main trigger the CI pipeline, which includes:
-
-1. **Flake Check** - 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
+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`
 
 ### Viewing CI Status
 
-Check the CI status badge at the top of the README or view detailed logs:
-
 ```bash
-# View workflow status
+# Web interface
 https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions
+
+# Or check locally
+git log --oneline -n 5
+# Look for ✓ or ✗ next to commits
 ```
 
 ### Running CI Checks Locally
 
-Before pushing changes, run the same checks that CI performs:
+Test before pushing:
 
 ```bash
-# Run all checks
+# Flake check
 nix flake check --show-trace
 
-# Check formatting
-nix fmt
-git diff --exit-code  # Should return no changes
+# Format check
+nix fmt --check
 
-# Build specific configuration
-nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel
+# Format code
+nix fmt **/*.nix
 
-# Build artifacts
-nix build .#lxc-nix-builder
+# Build key configurations
+nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel -L
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
 ```
 
-### Self-Hosted Runner
+## Common Tasks
 
-CI jobs run on the `nix-builder` host as a self-hosted Gitea Actions runner. This provides:
+### Adding a New Host
 
-- Native Nix environment without installation overhead
-- Access to local Nix store for faster builds
-- Consistent build environment matching deployment targets
-- Direct access to build caching infrastructure
-
-#### Setting Up the Gitea Actions Runner
-
-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
-   ```
-
-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
-
-# Commit if successful
-git add flake.lock
-git commit -m "Update flake inputs"
-git push
-```
-
-### Update Specific Input
-
-```bash
-# Update only nixpkgs
-nix flake lock --update-input nixpkgs
-
-# Update home-manager
-nix flake lock --update-input home-manager
-
-# Update multiple specific inputs
-nix flake lock --update-input nixpkgs --update-input home-manager
-```
-
-### Check for Security Updates
-
-```bash
-# After updating, check for known vulnerabilities
-nix flake check
-
-# Review nixpkgs changelog
-git log HEAD..nixpkgs/nixos-25.11 --oneline | head -20
-```
-
-## Adding Packages
-
-### System-Wide Packages by Type
-
-Add packages based on system type:
-
-**Desktop systems:**
-```bash
-# Edit sw/desktop/programs.nix
-vim sw/desktop/programs.nix
-```
-
-**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`:
+Edit `inventory.nix`:
 
 ```nix
-nix-laptop = {
-  devices = 2;
+nix-surface = {
+  devices = 3;  # Creates nix-surface1, nix-surface2, nix-surface3
   overrides = {
-    athenix.sw.extraPackages = with pkgs; [
-      vim
-      docker
-      kubernetes-helm
-    ];
+    athenix.sw.type = "tablet-kiosk";
+    athenix.sw.kioskUrl = "https://dashboard.example.com";
   };
 };
 ```
 
-### User-Specific Packages
-
-Add to user's home-manager configuration in their external `user.nix`:
-
-```nix
-# In external user.nix
-home.packages = with pkgs; [
-  ripgrep
-  fd
-  bat
-];
-```
-
-### Search for Packages
+Test:
 
 ```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
-athenix.sw.python.enable = true;  # Default: enabled
-```
-
-## Contributing
-
-### Code Style
-
-- Run formatter before committing: `nix fmt`
-- Follow existing code structure and conventions
-- Add comments for complex logic
-- Use the `athenix.*` namespace for all custom options
-
-### Testing Workflow
-
-1. Make changes
-2. Run formatter: `nix fmt`
-3. Test locally: `nix flake check`
-4. Test specific builds if needed
-5. Commit changes
-6. Push to GitHub
-
-```bash
-# Full workflow
-nix fmt
 nix flake check
-git add .
-git commit -m "Description of changes"
-git push
+nix build .#installer-iso-nix-surface1 -L
 ```
 
-### Documentation
+### Modifying Software Configuration
 
-Update relevant documentation when making changes:
-
-- `README.md` - Overview and quick start
-- `docs/INVENTORY.md` - Inventory configuration
-- `docs/NAMESPACE.md` - Configuration options
-- `USER_CONFIGURATION.md` - User management
-- `EXTERNAL_MODULES.md` - External modules
-
-### Creating Issues
-
-When reporting bugs or requesting features:
-
-1. Check existing issues first
-2. Provide clear description
-3. Include error messages and traces
-4. Specify which hosts are affected
-5. Include `flake.lock` info if relevant
-
-## Useful Commands
+Edit appropriate file in `sw/`:
 
 ```bash
-# Show all available outputs
-nix flake show
+# Desktop software
+vim sw/desktop/programs.nix
 
-# Evaluate specific option
-nix eval .#nixosConfigurations.nix-laptop1.config.networking.hostName
+# Or for all systems
+vim sw/default.nix
+```
 
+Use `athenix.sw.extraPackages` for host-specific additions:
+
+```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
+  ];
+}
+```
+
+### Using External Configurations
+
+For user dotfiles:
+
+```nix
+# users.nix
+athenix.users.myuser.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/username/dotfiles";
+  rev = "abc123...";  # Pin to commit
+};
+```
+
+For system config:
+
+```nix
+# inventory.nix
+nix-lxc = {
+  devices."server" = builtins.fetchGit {
+    url = "https://git.factory.uga.edu/org/server-config";
+    rev = "abc123...";
+  };
+};
+```
+
+### Updating Dependencies
+
+```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"
+```
+
+## Debugging
+
+### Verbose Output
+
+Get detailed error messages:
+
+```bash
+# Show full error traces
+nix flake check --show-trace
+
+# With maximum verbosity
+nix build .#installer-iso-nix-laptop1 -vvv
+
+# 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
 
-# Check flake metadata
-nix flake metadata
+# Show flake structure
+nix flake show | head -50
 
-# Show evaluation trace
-nix eval --show-trace .#nixosConfigurations.nix-laptop1
+# Check Nix store size
+du -sh /nix/store
 
-# Build and enter debug shell
-nix develop
+# List top space users in store
+nix store du --human-readable | head -20
 
-# Clean up old generations
-nix-collect-garbage -d
-
-# Optimize Nix store
-nix store optimise
+# Find store paths for a package
+nix store path-info -rS $(which some-package)
 ```
 
+### Getting Help
+
+1. **Check documentation** - Review relevant doc file
+2. **Look at existing examples** - Check `inventory.nix` or `users.nix`
+3. **Search for similar patterns** - `grep -r "athenix.option" .`
+4. **Run tests locally** - `nix flake check --show-trace` with full output
+5. **Review git history** - `git log --patch -- filename.nix`
+
 ## See Also
 
-- [README.md](../README.md) - Main documentation
-- [INVENTORY.md](INVENTORY.md) - Host inventory configuration
-- [BUILDING.md](BUILDING.md) - Building installation media
+- [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

docs/EXTERNAL_MODULES.md

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

docs/INVENTORY.md

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

docs/NAMESPACE.md

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

docs/USER_CONFIGURATION.md

@@ -1,103 +1,585 @@
 # User Configuration Guide
 
-Complete guide to managing user accounts in nixos-systems.
+Comprehensive guide to managing user accounts in Athenix.
 
 ## Table of Contents
 
 - [Overview](#overview)
 - [Quick Start](#quick-start)
-- [User Account Options](#user-account-options)
-- [External User Configurations](#external-user-configurations)
+- [Defining Users](#defining-users)
 - [Enabling Users on Hosts](#enabling-users-on-hosts)
+- [External User Configurations](#external-user-configurations)
 - [Password Management](#password-management)
 - [SSH Keys](#ssh-keys)
+- [User Groups](#user-groups)
 - [Examples](#examples)
 
 ## Overview
 
-Users are defined in `users.nix` but are **not enabled by default** on all systems. Each system must explicitly enable users in `inventory.nix`.
+User accounts are defined in `users.nix` but are **not enabled by default**. Each host must explicitly enable users in `inventory.nix`.
 
-**Default enabled users:**
-- `root` - System administrator
-- `engr-ugaif` - Innovation Factory default account
+**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.
 
 ## Quick Start
 
 ### 1. Define User in users.nix
 
 ```nix
-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... user@machine"
-    ];
-  };
-  
-  # Option 2: External configuration (recommended for personalization)
-  myuser.external = builtins.fetchGit {
-    url = "https://git.factory.uga.edu/username/dotfiles";
-    rev = "abc123...";  # Pin to specific commit
-  };
+athenix.users.myuser = {
+  description = "John Doe";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
 };
 ```
 
-### 2. Enable User on Hosts
-
-In `inventory.nix`:
+### 2. Enable on Hosts 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
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
 };
 ```
 
-## User Account Options
+### 3. Users can now log in
 
-Each user in `users.nix` can have the following options:
+Users defined and enabled this way are automatically created on the system.
+
+## Defining Users
+
+Define users in `users.nix` under `athenix.users`:
+
+### Inline User Definition
 
 ```nix
-username = {
-  # === Identity ===
-  description = "Full Name";              # User's full name
+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 {
+  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
+
+See [External User Configurations](#external-user-configurations) section below.
+
+## User Account Options
+
+### `description`
+
+Full name or description of the user.
+
+**Type:** String
+
+```nix
+athenix.users.myuser.description = "John Doe";
+```
+
+### `extraGroups`
+
+Additional Unix groups for the user. Default is empty.
+
+**Type:** List of strings
+
+**Common groups:**
+- `"wheel"` - Sudo access
+- `"networkmanager"` - Network configuration
+- `"docker"` - Docker and Podman access
+- `"video"` - Video device access (GPU, displays)
+- `"audio"` - Audio device access
+- `"input"` - Input devices (keyboards, mice)
+- `"kvm"` - KVM virtual machine access
+- `"libvirtd"` - Libvirt daemon access
+
+```nix
+athenix.users.myuser.extraGroups = [
+  "wheel"
+  "networkmanager"
+  "docker"
+  "video"
+];
+```
+
+### `shell`
+
+Login shell for the user.
+
+**Type:** Package
+
+**Default:** `pkgs.bash`
+
+```nix
+athenix.users.myuser.shell = pkgs.zsh;
+# or
+athenix.users.myuser.shell = pkgs.fish;
+```
+
+### `hashedPassword`
+
+Password hash for the user. Use `!` to disable password login (SSH keys only).
+
+**Type:** String (SHA-512 hash)
+
+**Generation:**
+```bash
+# Generate a hashed password
+mkpasswd -m sha-512
+
+# Or interactively
+mkpasswd -m sha-512 -c
+```
+
+```nix
+athenix.users.myuser.hashedPassword = "$6$...";
+
+# Disable password login (require SSH keys)
+athenix.users.myuser.hashedPassword = "!";
+```
+
+### `opensshKeys`
+
+SSH public keys for remote access. Users without SSH keys require password login.
+
+**Type:** List of strings
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@laptop"
+  "ssh-rsa AAAA... user@desktop"
+];
+```
+
+**Getting your SSH public key:**
+```bash
+# Print your public key
+cat ~/.ssh/id_ed25519.pub
+
+# Generate a new key if needed
+ssh-keygen -t ed25519 -C "user@host"
+```
+
+### `useZshTheme`
+
+Apply system Zsh theme configuration to this user (if using Zsh as shell).
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useZshTheme = true;
+```
+
+### `useNvimPlugins`
+
+Apply system Neovim configuration and plugins to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useNvimPlugins = true;
+```
+
+## Enabling Users on Hosts
+
+Users are **not enabled by default**. Enable them in `inventory.nix`:
+
+### Enable on All Devices in a Group
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+### Enable on Specific Devices
+
+```nix
+nix-desktop = {
+  devices = {
+    "1".athenix.users.admin.enable = true;
+    "2".athenix.users.staff.enable = true;
+    "3".athenix.users.staff.enable = true;
+  };
+};
+```
+
+### Enable Multiple Users
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides = {
+    athenix.users.student.enable = true;
+    athenix.users.teacher.enable = true;
+  };
+};
+```
+
+### Using `athenix.forUser` Convenience
+
+Quick setup for single-user systems (especially WSL):
+
+```nix
+nix-wsl = {
+  devices = {
+    "alice".athenix.forUser = "alice-uga";
+    "bob".athenix.forUser = "bob-uga";
+  };
+};
+```
+
+This automatically enables the user and sets it as the default WSL user.
+
+## External User Configurations
+
+External user configurations (dotfiles) allow users to maintain their own home-manager setup in separate repositories.
+
+### Repository Structure
+
+```
+my-dotfiles/
+├── user.nix      # Required: User options + home-manager config
+├── nixos.nix     # Optional: System-level configuration
+└── config/       # Optional: Your actual dotfiles
+    ├── bashrc
+    ├── zshrc
+    ├── vimrc
+    └── ...
+```
+
+### user.nix (Required)
+
+This file must provide BOTH user account options AND home-manager configuration:
+
+```nix
+{ inputs, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
+{
+  # ========== User Account Configuration ==========
+  # These options define the user account itself
+  athenix.users.myusername = {
+    description = "My Full Name";
+    extraGroups = [ "wheel" "docker" "networkmanager" ];
+    shell = pkgs.zsh;
+    hashedPassword = "!";  # SSH keys only
+    opensshKeys = [
+      "ssh-ed25519 AAAA... user@host"
+    ];
+    useZshTheme = true;
+    useNvimPlugins = true;
+  };
+
+  # ========== Home Manager Configuration ==========
+  # User environment, packages, and dotfiles
   
-  # === 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
+  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"
   ];
-  shell = pkgs.zsh;                       # Login shell (default: pkgs.bash)
-  hashedPassword = "$6$...";              # Hashed password (see below)
-  
-  # === SSH Access ===
-  opensshKeys = [                         # SSH public keys
-    "ssh-ed25519 AAAA... user@host"
-    "ssh-rsa AAAA... user@otherhost"
-  ];
-  
-  # === External Configuration ===
+  useZshTheme = true;
+  useNvimPlugins = true;
+};
+
+# inventory.nix
+nix-desktop = {
+  devices = 3;
+  overrides.athenix.users.developer.enable = true;
+};
+```
+
+### Example 3: WSL User with Dotfiles
+
+```nix
+# users.nix
+athenix.users.alice.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/alice/dotfiles";
+  rev = "abc123...";
+};
+
+# inventory.nix
+nix-wsl = {
+  devices = {
+    "alice".athenix.forUser = "alice-uga";
+  };
+};
+```
+
+### Example 4: Multiple Users on Single System
+
+```nix
+# users.nix
+athenix.users = {
+  admin = {
+    description = "System Administrator";
+    extraGroups = [ "wheel" ];
+    shell = pkgs.bash;
+    hashedPassword = "!";
+    opensshKeys = [ "ssh-ed25519 AAAA..." ];
+  };
+  guest = {
+    description = "Guest User";
+    extraGroups = [];
+    shell = pkgs.bash;
+    hashedPassword = "$6$...";
+  };
+};
+
+# inventory.nix
+nix-desktop = {
+  devices = {
+    "admin-station" = {
+      athenix.users.admin.enable = true;
+    };
+    "guest-station" = {
+      athenix.users.guest.enable = true;
+    };
+  };
+};
+```
+
+## See Also
+
+- [INVENTORY.md](INVENTORY.md) - Host configuration
+- [NAMESPACE.md](NAMESPACE.md) - All configuration options
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External modules in detail
+- [README.md](../README.md) - Main documentation
   external = builtins.fetchGit { ... };   # External user module (see below)
   
   # === Theme Integration ===

inventory.nix

@@ -121,7 +121,7 @@
         };
       };
       "usda-dash" = builtins.fetchGit {
-        url = "git@factory.uga.edu:MODEL/usda-dash-config.git";
+        url = "https://git.factory.uga.edu/MODEL/usda-dash-config.git";
         rev = "dab32f5884895cead0fae28cb7d88d17951d0c12";
         submodules = true;
       };