docs: Update inline docs and make home-manager module exports

flake.nix

@@ -92,7 +92,18 @@
       # Expose artifacts to all systems, but they are always built for x86_64-linux
       packages = forAllSystems (_: artifacts);
 
-      # Expose host type modules for external use
+      # Expose modules for external use
-      nixosModules = import ./installer/modules.nix { inherit inputs; };
+      nixosModules =
+        let
+          modules = import ./installer/modules.nix { inherit inputs; };
+        in
+        nixpkgs.lib.filterAttrs (n: _: n != "homeModules") modules;
+
+      # Expose Home Manager modules separately
+      homeModules =
+        let
+          modules = import ./installer/modules.nix { inherit inputs; };
+        in
+        modules.homeModules or { };
     };
 }

hosts/boot.nix

@@ -1,15 +1,15 @@
-# Edit this configuration file to define what should be installed on
-# your system.  Help is available in the configuration.nix(5) man page
-# and in the NixOS manual (accessible by running ‘nixos-help’).
-
-{ config, lib, ... }:
-
 # ============================================================================
 # Boot & Storage Configuration
 # ============================================================================
-# This module defines the Disko partition layout and bootloader settings.
+# This module defines:
-# It exposes 'ugaif.host.filesystem' options to allow per-host overrides of
+# - Disko partition layout (EFI, swap, root)
-# the target device and swap size.
+# - Bootloader configuration (systemd-boot with Plymouth)
+# - Filesystem options (device, swap size)
+# - Build method options (ISO, iPXE, LXC, Proxmox)
+# - Garbage collection settings
+# - Convenience options (forUser, useHostPrefix)
+
+{ config, lib, ... }:
 
 {
   options.ugaif = {
@@ -79,7 +79,7 @@
   };
 
   config = {
-    # Enable Disko for declarative partitioning
+    # ========== Disk Partitioning (Disko) ==========
     disko.enableConfig = lib.mkDefault true;
 
     disko.devices = {

hosts/types/nix-desktop.nix

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

hosts/types/nix-ephemeral.nix

@@ -1,3 +1,10 @@
+# ============================================================================
+# Ephemeral/Diskless System Configuration
+# ============================================================================
+# Configuration for systems that run entirely from RAM without persistent storage.
+# Suitable for kiosks, netboot clients, and stateless workstations.
+# All data is lost on reboot.
+
 { inputs, ... }:
 {
   config,
@@ -6,43 +13,43 @@
   ...
 }:
 {
-  # This host type is for ephemeral, diskless systems (e.g. kiosks, netboot clients).
-  # It runs entirely from RAM and does not persist state across reboots.
   imports = [
     (import ../common.nix { inherit inputs; })
     (modulesPath + "/installer/scan/not-detected.nix")
   ];
 
+  # ========== Boot Configuration ==========
   boot.initrd.availableKernelModules = [
-    "xhci_pci"
+    "xhci_pci"    # USB 3.0 support
-    "nvme"
+    "nvme"        # NVMe support
-    "usb_storage"
+    "usb_storage" # USB storage devices
-    "sd_mod"
+    "sd_mod"      # SD card support
-    "sdhci_pci"
+    "sdhci_pci"   # SD card host controller
   ];
   boot.initrd.kernelModules = [ ];
-  boot.kernelModules = [ "kvm-intel" ];
+  boot.kernelModules = [ "kvm-intel" ]; # Intel virtualization support
   boot.extraModulePackages = [ ];
   boot.kernelParams = [
-    "quiet"
+    "quiet"                       # Minimal boot messages
-    "splash"
+    "splash"                      # Show Plymouth boot splash
-    "boot.shell_on_fail"
+    "boot.shell_on_fail"          # Emergency shell on boot failure
-    "udev.log_priority=3"
+    "udev.log_priority=3"         # Reduce udev logging
-    "rd.systemd.show_status=auto"
+    "rd.systemd.show_status=auto" # Show systemd status during boot
   ];
 
-  # Ephemeral setup: No swap, no disk
+  # ========== Ephemeral Configuration ==========
+  # No persistent storage - everything runs from RAM
   ugaif.host.filesystem.swapSize = lib.mkForce "0G";
   ugaif.host.filesystem.device = lib.mkForce "/dev/null"; # Dummy device
   ugaif.host.buildMethods = lib.mkDefault [
-    "iso"
+    "iso"   # Live ISO image
-    "ipxe"
+    "ipxe"  # Network boot
   ];
 
-  # Disable Disko config since we are running from RAM/ISO
+  # Disable disk management for RAM-only systems
   disko.enableConfig = lib.mkForce false;
 
-  # Define a dummy root filesystem to satisfy assertions
+  # Define tmpfs root filesystem
   fileSystems."/" = {
     device = "none";
     fsType = "tmpfs";

hosts/types/nix-laptop.nix

@@ -1,3 +1,9 @@
+# ============================================================================
+# Laptop Configuration
+# ============================================================================
+# Hardware and boot configuration for laptop systems with mobile features.
+# Includes power management, lid switch handling, and Intel graphics fixes.
+
 { inputs, ... }:
 {
   config,
@@ -11,36 +17,40 @@
     (modulesPath + "/installer/scan/not-detected.nix")
   ];
 
+  # ========== Boot Configuration ==========
+
   boot.initrd.availableKernelModules = [
-    "xhci_pci"
+    "xhci_pci"    # USB 3.0 support
-    "thunderbolt"
+    "thunderbolt" # Thunderbolt support
-    "nvme"
+    "nvme"        # NVMe SSD support
-    "usb_storage"
+    "usb_storage" # USB storage devices
-    "sd_mod"
+    "sd_mod"      # SD card support
-    "sdhci_pci"
+    "sdhci_pci"   # SD card host controller
   ];
   boot.initrd.kernelModules = [ ];
-  boot.kernelModules = [ "kvm-intel" ];
+  boot.kernelModules = [ "kvm-intel" ]; # Intel virtualization support
   boot.extraModulePackages = [ ];
   boot.kernelParams = [
-    "quiet"
+    "quiet"                       # Minimal boot messages
-    "splash"
+    "splash"                      # Show Plymouth boot splash
-    "boot.shell_on_fail"
+    "boot.shell_on_fail"          # Emergency shell on boot failure
-    "udev.log_priority=3"
+    "udev.log_priority=3"         # Reduce udev logging
-    "rd.systemd.show_status=auto"
+    "rd.systemd.show_status=auto" # Show systemd status during boot
-    "i915.enable_psr=0"
+    "i915.enable_psr=0"           # Disable Panel Self Refresh (stability)
-    "i915.enable_dc=0"
+    "i915.enable_dc=0"            # Disable display power saving
-    "i915.enable_fbc=0"
+    "i915.enable_fbc=0"           # Disable framebuffer compression
   ];
 
+  # ========== Hardware Configuration ==========
   nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
   hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
 
+  # ========== Filesystem Configuration ==========
   ugaif.host.filesystem.device = lib.mkDefault "/dev/nvme0n1";
-  ugaif.host.filesystem.swapSize = lib.mkDefault "34G";
+  ugaif.host.filesystem.swapSize = lib.mkDefault "34G"; # Larger swap for hibernation
   ugaif.host.buildMethods = lib.mkDefault [ "installer-iso" ];
 
-  # Suspend / logind behavior
+  # ========== Power Management ==========
   services.upower.enable = lib.mkDefault true;
   services.logind.settings = {
     Login = {

hosts/types/nix-lxc.nix

@@ -1,3 +1,9 @@
+# ============================================================================
+# Proxmox LXC Container Configuration
+# ============================================================================
+# Configuration for lightweight Linux containers running in Proxmox.
+# Disables boot/disk management and enables remote development support.
+
 { inputs, ... }:
 {
   config,
@@ -12,6 +18,7 @@
     "${modulesPath}/virtualisation/proxmox-lxc.nix"
   ];
 
+  # ========== Nix Configuration ==========
   nix.settings.trusted-users = [
     "root"
     "engr-ugaif"
@@ -21,24 +28,33 @@
     "flakes"
   ];
 
+  # ========== Container-Specific Configuration ==========
   boot.isContainer = true;
-  boot.loader.systemd-boot.enable = lib.mkForce false;
+  boot.loader.systemd-boot.enable = lib.mkForce false; # No bootloader in container
-  disko.enableConfig = lib.mkForce false;
+  disko.enableConfig = lib.mkForce false;              # No disk management in container
   console.enable = true;
+  
+  # Allow getty to work in containers
   systemd.services."getty@".unitConfig.ConditionPathExists = [
     ""
     "/dev/%I"
   ];
+  
+  # Suppress unnecessary systemd units for containers
   systemd.suppressedSystemUnits = [
     "dev-mqueue.mount"
     "sys-kernel-debug.mount"
     "sys-fs-fuse-connections.mount"
   ];
+  
+  # ========== Remote Development ==========
   services.vscode-server.enable = true;
+  
+  # ========== System Configuration ==========
   system.stateVersion = "25.11";
   ugaif.host.buildMethods = lib.mkDefault [
-    "lxc"
+    "lxc"      # LXC container tarball
-    "proxmox"
+    "proxmox"  # Proxmox VMA archive
   ];
 
   ugaif.sw.enable = lib.mkDefault true;

hosts/types/nix-surface.nix

@@ -1,3 +1,9 @@
+# ============================================================================
+# Microsoft Surface Tablet Configuration
+# ============================================================================
+# Hardware configuration for Surface Go tablets in kiosk mode.
+# Uses nixos-hardware module and older kernel for Surface-specific drivers.
+
 { inputs, ... }:
 {
   config,
@@ -7,6 +13,7 @@
   ...
 }:
 let
+  # Use older kernel version for better Surface Go compatibility
   refSystem = inputs.nixpkgs-old-kernel.lib.nixosSystem {
     system = pkgs.stdenv.hostPlatform.system;
     modules = [ inputs.nixos-hardware.nixosModules.microsoft-surface-go ];
@@ -20,38 +27,44 @@ in
     inputs.nixos-hardware.nixosModules.microsoft-surface-go
   ];
 
+  # ========== Boot Configuration ==========
+
   boot.initrd.availableKernelModules = [
-    "xhci_pci"
+    "xhci_pci"    # USB 3.0 support
-    "nvme"
+    "nvme"        # NVMe support (though Surface uses eMMC)
-    "usb_storage"
+    "usb_storage" # USB storage devices
-    "sd_mod"
+    "sd_mod"      # SD card support
-    "sdhci_pci"
+    "sdhci_pci"   # SD card host controller
   ];
   boot.initrd.kernelModules = [ ];
-  boot.kernelModules = [ "kvm-intel" ];
+  boot.kernelModules = [ "kvm-intel" ]; # Intel virtualization support
   boot.extraModulePackages = [ ];
   boot.kernelParams = [
-    "quiet"
+    "quiet"                       # Minimal boot messages
-    "splash"
+    "splash"                      # Show Plymouth boot splash
-    "boot.shell_on_fail"
+    "boot.shell_on_fail"          # Emergency shell on boot failure
-    "udev.log_priority=3"
+    "udev.log_priority=3"         # Reduce udev logging
-    "rd.systemd.show_status=auto"
+    "rd.systemd.show_status=auto" # Show systemd status during boot
-    "intel_ipu3_imgu"
+    "intel_ipu3_imgu"             # Intel camera image processing
-    "intel_ipu3_isys"
+    "intel_ipu3_isys"             # Intel camera sensor interface
-    "fbcon=map:1"
+    "fbcon=map:1"                 # Framebuffer console mapping
-    "i915.enable_psr=0" # Panel Self Refresh breaks resume on Surface
+    "i915.enable_psr=0"           # Disable Panel Self Refresh (breaks resume)
-    "i915.enable_dc=0"
+    "i915.enable_dc=0"            # Disable display power saving
   ];
 
+  # Use older kernel for better Surface hardware support
   boot.kernelPackages = lib.mkForce refKernelPackages;
 
+  # ========== Filesystem Configuration ==========
   ugaif.host.filesystem.swapSize = lib.mkDefault "8G";
-  ugaif.host.filesystem.device = lib.mkDefault "/dev/mmcblk0";
+  ugaif.host.filesystem.device = lib.mkDefault "/dev/mmcblk0"; # eMMC storage # eMMC storage
   ugaif.host.buildMethods = lib.mkDefault [ "installer-iso" ];
   nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
 
+  # ========== Hardware Configuration ==========
   hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
 
+  # ========== Software Profile ==========
   ugaif.sw.enable = lib.mkDefault true;
-  ugaif.sw.type = lib.mkDefault "tablet-kiosk";
+  ugaif.sw.type = lib.mkDefault "tablet-kiosk"; # Touch-optimized kiosk mode
 }

hosts/types/nix-wsl.nix

@@ -1,3 +1,9 @@
+# ============================================================================
+# Windows Subsystem for Linux (WSL) Configuration
+# ============================================================================
+# Configuration for NixOS running in WSL2 on Windows.
+# Integrates with nixos-wsl for WSL-specific functionality.
+
 { inputs, ... }:
 {
   lib,
@@ -11,6 +17,7 @@
     inputs.vscode-server.nixosModules.default
   ];
 
+  # ========== Options ==========
   options.ugaif.host.wsl.user = lib.mkOption {
     type = lib.types.str;
     default = "engr-ugaif";
@@ -18,23 +25,26 @@
   };
 
   config = {
+    # ========== WSL Configuration ==========
     wsl.enable = true;
+    # Use forUser if set, otherwise fall back to wsl.user option
     wsl.defaultUser =
       if config.ugaif.forUser != null then config.ugaif.forUser else config.ugaif.host.wsl.user;
 
-    # Enable the headless software profile
+    # ========== Software Profile ==========
     ugaif.sw.enable = lib.mkDefault true;
     ugaif.sw.type = lib.mkDefault "headless";
 
-    # Fix for VS Code Server in WSL if needed, though vscode-server input exists
+    # ========== Remote Development ==========
     services.vscode-server.enable = true;
 
-    # Disable Disko and Bootloader for WSL
+    # ========== Disable Irrelevant Systems ==========
+    # WSL doesn't use traditional boot or disk management
     disko.enableConfig = lib.mkForce false;
     boot.loader.systemd-boot.enable = lib.mkForce false;
     boot.loader.grub.enable = lib.mkForce false;
 
-    # Disable networking for wsl (it manages its own networking)
+    # WSL manages its own networking
     systemd.network.enable = lib.mkForce false;
 
     # Provide dummy values for required options from boot.nix

installer/modules.nix

@@ -10,12 +10,25 @@
 #   inputs.nixos-systems.nixosModules.nix-laptop
 #
 #   # Software-only configurations (for custom hardware setups)
+#   # Note: These include theme.nix in home-manager.sharedModules automatically
 #   inputs.nixos-systems.nixosModules.sw-desktop
 #   inputs.nixos-systems.nixosModules.sw-headless
+#
+#   # Home Manager modules (user-level configuration)
+#   # Theme module (no parameters):
+#   home-manager.users.myuser.imports = [ inputs.nixos-systems.homeManagerModules.theme ];
+#
+#   # Neovim module (requires user parameter):
+#   home-manager.users.myuser.imports = [ 
+#     (inputs.nixos-systems.homeManagerModules.nvim { 
+#       user = config.ugaif.users.accounts.myuser;
+#     }) 
+#   ];
 
 { inputs }:
 let
-  # Software modules with their dependencies bundled
+  # Helper function to create software-only modules
+  # Bundles common system-level software with profile-specific config
   mkSwModule =
     swType:
     {
@@ -26,10 +39,8 @@ let
     }:
     {
       imports = [
-        ../sw/ghostty.nix
+        ../sw/ghostty.nix   # Terminal emulator
-        ../sw/nvim.nix
+        ../sw/python.nix    # Python environment
-        ../sw/python.nix
-        ../sw/theme.nix
         (import ../sw/${swType} {
           inherit
             config
@@ -39,20 +50,42 @@ let
             ;
         })
       ];
+
+      # Apply Home Manager modules to all users via sharedModules
+      # This ensures consistent shell theme across all users
+      home-manager.sharedModules = [
+        ../sw/theme.nix
+      ];
     };
+
+  # Helper to create a Home Manager module for nvim (requires user context)
+  # External users can import this with their user data
+  mkNvimModule =
+    user:
+    (import ../sw/nvim.nix { inherit user; });
 in
 {
-  # Host type modules (full system configurations)
+  # ========== Full Host Type Modules ==========
-  nix-desktop = import ../hosts/types/nix-desktop.nix { inherit inputs; };
+  # Complete system configurations including hardware, boot, and software
-  nix-laptop = import ../hosts/types/nix-laptop.nix { inherit inputs; };
+  nix-desktop = import ../hosts/types/nix-desktop.nix { inherit inputs; };     # Desktop workstations
-  nix-surface = import ../hosts/types/nix-surface.nix { inherit inputs; };
+  nix-laptop = import ../hosts/types/nix-laptop.nix { inherit inputs; };       # Laptop systems
-  nix-lxc = import ../hosts/types/nix-lxc.nix { inherit inputs; };
+  nix-surface = import ../hosts/types/nix-surface.nix { inherit inputs; };     # Surface tablets
-  nix-wsl = import ../hosts/types/nix-wsl.nix { inherit inputs; };
+  nix-lxc = import ../hosts/types/nix-lxc.nix { inherit inputs; };             # Proxmox containers
-  nix-ephemeral = import ../hosts/types/nix-ephemeral.nix { inherit inputs; };
+  nix-wsl = import ../hosts/types/nix-wsl.nix { inherit inputs; };             # WSL2 systems
+  nix-ephemeral = import ../hosts/types/nix-ephemeral.nix { inherit inputs; }; # Diskless/RAM-only
 
-  # Software-only modules (for mixing with custom hardware configs)
+  # ========== Software-Only Modules (NixOS) ==========
-  sw-desktop = mkSwModule "desktop";
+  # For use with custom hardware configurations
-  sw-headless = mkSwModule "headless";
+  sw-desktop = mkSwModule "desktop";                   # Full desktop environment
-  sw-stateless-kiosk = mkSwModule "stateless-kiosk";
+  sw-headless = mkSwModule "headless";                 # CLI-only systems
-  sw-tablet-kiosk = mkSwModule "tablet-kiosk";
+  sw-stateless-kiosk = mkSwModule "stateless-kiosk";   # Netboot kiosk
+  sw-tablet-kiosk = mkSwModule "tablet-kiosk";         # Touch-based kiosk
+
+  # ========== Home Manager Modules ==========
+  # User-level configuration modules
+  # Usage: home-manager.users.myuser.imports = [ (inputs.nixos-systems.homeManagerModules.nvim { user = <user-data>; }) ];
+  homeModules = {
+    theme = ../sw/theme.nix;                           # Zsh theme (no params needed)
+    nvim = mkNvimModule;                               # Neovim (requires user param)
+  };
 }

sw/default.nix

@@ -60,24 +60,26 @@ in
 
   config = mkIf cfg.enable (mkMerge [
     {
+      # ========== System-Wide Configuration ==========
       nixpkgs.config.allowUnfree = true;
 
+      # ========== Shell Configuration ==========
       programs.zsh.enable = true;
-      programs.nix-ld.enable = true;
+      programs.nix-ld.enable = true; # Allow running non-NixOS binaries
 
+      # ========== Base Packages ==========
       environment.systemPackages =
         with pkgs;
         subtractLists cfg.excludePackages [
-          htop
+          htop      # System monitor
-          binutils
+          binutils  # Binary utilities
-          zsh
+          zsh       # Z shell
-          git
+          git       # Version control
-          oh-my-posh
+          oh-my-posh # Shell prompt theme
-          # inputs.lazyvim-nixvim.packages.${stdenv.hostPlatform.system}.nvim
+          inputs.agenix.packages.${stdenv.hostPlatform.system}.default # Secret management
-          inputs.agenix.packages.${stdenv.hostPlatform.system}.default
         ];
     }
-    # Import Desktop or Kiosk modules based on type
+    # ========== Software Profile Imports ==========
     (mkIf (cfg.type == "desktop") (
       import ./desktop {
         inherit

sw/desktop/default.nix

@@ -1,3 +1,8 @@
+# ============================================================================
+# Desktop Software Configuration
+# ============================================================================
+# Imports desktop-specific programs and services (KDE Plasma, CUPS, etc.)
+
 {
   config,
   lib,

sw/headless/default.nix

@@ -1,3 +1,8 @@
+# ============================================================================
+# Headless Software Configuration
+# ============================================================================
+# Imports headless-specific programs and services (SSH, minimal CLI tools)
+
 {
   config,
   lib,

sw/nvim.nix

@@ -1,3 +1,10 @@
+# ============================================================================
+# Neovim Home Manager Configuration
+# ============================================================================
+# Provides conditional Neovim configuration based on user preferences.
+# - If useNvimPlugins=true: Full LazyVim distribution with plugins
+# - If useNvimPlugins=false: Plain Neovim without plugins
+
 { user }:
 {
   pkgs,
@@ -6,23 +13,19 @@
   ...
 }:
 let
+  # Choose Neovim package based on user preference
   nvimPackages =
     if user.useNvimPlugins then
-      [
+      [ inputs.lazyvim-nixvim.packages.${pkgs.stdenv.hostPlatform.system}.nvim ]
-        inputs.lazyvim-nixvim.packages.${pkgs.stdenv.hostPlatform.system}.nvim
-      ]
     else
       [ pkgs.neovim ];
 in
 {
-  # ============================================================================
-  # Neovim Configuration
-  # ============================================================================
-  # This module configures Neovim, specifically setting up TreeSitter parsers
-  # to ensure syntax highlighting works correctly.
 
   home.packages = nvimPackages;
 
+  # Configure TreeSitter parsers for syntax highlighting
+  # Only needed when using plugins (LazyVim includes TreeSitter)
   # https://github.com/nvim-treesitter/nvim-treesitter#i-get-query-error-invalid-node-type-at-position
   xdg.configFile."nvim/parser".source = lib.mkIf user.useNvimPlugins (
     let