docs: Overhaul all the documentation

README.md

@@ -78,7 +78,7 @@ nix-laptop = {
 
 ### Using External Flakes for User Configuration
 
-Users can manage their own Home Manager configuration in a separate flake repository. To use this:
+Users can manage their own configuration (both Home Manager and System-level settings) in a separate flake repository. To use this:
 
 1.  Open `users.nix`.
 2.  In the user's configuration block, set the `flakeUrl` option:
@@ -90,11 +90,11 @@ hdh20267 = {
 };
 ```
 
-The external flake must provide a `homeManagerModules.default` output. Note that using this feature may require running `update-system --impure` if the flake is not locked in the system's `flake.lock`.
+The external flake must provide a `nixosModules.default` output. This module is imported into the system configuration, allowing the user to override their own system settings (like `shell`, `extraGroups`) and define their Home Manager configuration.
 
 ### Using External Flakes for System Configuration
 
-You can also override the system-level configuration for a specific host using an external flake. This is useful for adding system services (like Docker), changing boot parameters, or installing system-wide packages that are not in the standard image.
+You can also override the system-level configuration for a specific host using an external flake. This is useful for adding system services (like Docker), changing boot parameters, installing system-wide packages, or even overriding hardware settings (like swap size) without modifying `inventory.nix`.
 
 1.  Open `inventory.nix`.
 2.  In the `devices` override for the host, set the `flakeUrl`:
@@ -105,48 +105,57 @@ nix-laptop = {
   devices = {
     "2" = { 
       flakeUrl = "github:myuser/my-system-config"; 
-      # You can still combine this with other overrides
-      swapSize = "64G";
     };
   };
 };
 ```
 
-The external flake must provide a `nixosModules.default` output.
+The external flake must provide a `nixosModules.default` output. Any configuration defined in that module will be merged with the host's configuration.
 
 ## External Flake Templates
 
 If you are creating a new flake to use with `flakeUrl`, use these templates as a starting point.
 
-### Home Manager Flake (for `users.nix`)
+### User Flake (for `users.nix`)
 
-Use this for user-specific dotfiles, shell configuration, and user packages.
+Use this for user-specific dotfiles, shell configuration, and user packages. It can also override system-level user settings.
+
+Note that `inputs` are omitted. This ensures the flake uses the exact same `nixpkgs` version as the main system, preventing version drift and saving disk space.
 
 ```nix
 {
-  description = "My Home Manager Configuration";
+  description = "My User Configuration";
 
-  inputs = {
+  # No inputs needed! We use the system's packages.
-    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-    # home-manager is not strictly required as an input if you only export a module,
-    # but it's good practice for standalone testing.
-  };
 
-  outputs = { self, nixpkgs, ... }: {
+  outputs = { self }: {
     # This output is what nixos-systems looks for
-    homeManagerModules.default = { pkgs, ... }: {
+    nixosModules.default = { pkgs, lib, ... }: {
-      home.stateVersion = "25.11";
       
-      home.packages = with pkgs; [ 
+      # 1. Override System-Level User Settings
-        ripgrep 
+      modules.users.accounts.hdh20267 = {
-        bat 
+        shell = pkgs.fish;
-        fzf
+        extraGroups = [ "docker" ];
-      ];
+      };
+      
+      # Enable programs needed for the shell
+      programs.fish.enable = true;
 
-      programs.git = {
+      # 2. Define Home Manager Configuration
-        enable = true;
+      home-manager.users.hdh20267 = { pkgs, ... }: {
-        userName = "My Name";
+        home.stateVersion = "25.11";
-        userEmail = "me@example.com";
+        
+        home.packages = with pkgs; [ 
+          ripgrep 
+          bat 
+          fzf
+        ];
+
+        programs.git = {
+          enable = true;
+          userName = "My Name";
+          userEmail = "me@example.com";
+        };
       };
     };
   };
@@ -161,17 +170,21 @@ Use this for host-specific system services, hardware tweaks, or root-level packa
 {
   description = "My System Configuration Override";
 
-  inputs = {
+  # No inputs needed! We use the system's packages.
-    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
-  };
 
-  outputs = { self, nixpkgs, ... }: {
+  outputs = { self }: {
     # This output is what nixos-systems looks for
-    nixosModules.default = { pkgs, ... }: {
+    nixosModules.default = { pkgs, lib, ... }: {
       environment.systemPackages = [ pkgs.docker ];
       
       virtualisation.docker.enable = true;
       
+      # Example: Override hardware settings defined in the main repo
+      host.filesystem.swapSize = lib.mkForce "64G";
+
+      # Example: Enable specific users
+      modules.users.enabledUsers = [ "myuser" ];
+      
       # Example: Add a custom binary cache
       nix.settings.substituters = [ "https://nix-community.cachix.org" ];
       nix.settings.trusted-public-keys = [ "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=" ];

flake.nix

@@ -1,21 +1,41 @@
 {
+  # ============================================================================
+  # Flake Entry Point
+  # ============================================================================
+  # This file defines the inputs (dependencies) and outputs (configurations)
+  # for the NixOS systems. It ties together the hardware, software, and user
+  # configurations into deployable systems.
+
   inputs = {
+    # Core NixOS package repository (Release 25.11)
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+    
+    # Older kernel packages for Surface compatibility if needed
     nixpkgs-old-kernel.url = "github:NixOS/nixpkgs/nixos-25.05";
+    
+    # Home Manager for user environment management
     home-manager = {
       url = "github:nix-community/home-manager/release-25.11";
       inputs.nixpkgs.follows = "nixpkgs";
     };
+    
+    # Disko for declarative disk partitioning
     disko = {
       url = "github:nix-community/disko";
       inputs.nixpkgs.follows = "nixpkgs";
     };
+    
+    # Hardware quirks and configurations
     nixos-hardware.url = "github:NixOS/nixos-hardware/master";
+    
+    # Neovim configuration
     lazyvim-nixvim.url = "github:azuwis/lazyvim-nixvim";
   };
   outputs = inputs@{ self, nixpkgs, nixpkgs-old-kernel, home-manager, disko, lazyvim-nixvim, nixos-hardware,... }: {
+    # Formatter for 'nix fmt'
     formatter.x86_64-linux = nixpkgs.legacyPackages.x86_64-linux.nixfmt-rfc-style;
 
+    # Generate NixOS configurations from hosts/default.nix
     nixosConfigurations = import ./hosts { inherit inputs; };
   };
 }

hosts/boot.nix

@@ -4,6 +4,13 @@
 
 { config, lib, ... }:
 
+# ============================================================================
+# Boot & Storage Configuration
+# ============================================================================
+# This module defines the Disko partition layout and bootloader settings.
+# It exposes 'host.filesystem' options to allow per-host overrides of
+# the target device and swap size.
+
 {
   options.host = {
     filesystem = {
@@ -19,6 +26,7 @@
   };
 
   config = {
+    # Enable Disko for declarative partitioning
     disko.enableConfig = true;
 
     disko.devices = {
@@ -28,6 +36,7 @@
         content = {
           type = "gpt";
           partitions = {
+            # EFI System Partition
             ESP = {
               name = "ESP";
               label = "BOOT";
@@ -42,6 +51,7 @@
               };
             };
 
+            # Swap Partition (size configurable per host)
             swap = {
               name = "swap";
               label = "swap";
@@ -49,6 +59,7 @@
               content = { type = "swap"; };
             };
 
+            # Root Partition (takes remaining space)
             root = {
               name = "root";
               label = "root";
@@ -65,7 +76,7 @@
       };
     };
 
-    # Bootloader.
+    # Bootloader Configuration
     boot = {
       loader.systemd-boot.enable = true;
       loader.efi.canTouchEfiVariables = true;

hosts/default.nix

@@ -1,11 +1,21 @@
 { inputs, hosts ? import ../inventory.nix, ... }:
 
+# ============================================================================
+# Host Generator
+# ============================================================================
+# This file contains the logic to generate NixOS configurations for all hosts
+# defined in inventory.nix. It handles:
+# 1. Common module imports (boot, users, software).
+# 2. Host-specific overrides (filesystem, enabled users).
+# 3. External flake integration for system overrides.
+
 let
   nixpkgs      = inputs.nixpkgs;
   lib          = nixpkgs.lib;
   home-manager = inputs.home-manager;
   disko        = inputs.disko;
 
+  # Modules shared by all hosts
   commonModules = [
     ./boot.nix
     ./user-config.nix
@@ -29,7 +39,23 @@ let
     }
   ];
 
+  # Helper to create a single NixOS system configuration
   mkHost = { hostName, system ? "x86_64-linux", extraModules ? [ ] }:
+    let
+      # Load users.nix to find external user flakes
+      # We use legacyPackages to evaluate the simple data structure of users.nix
+      pkgs = nixpkgs.legacyPackages.${system};
+      usersData = import ../users.nix { inherit pkgs; };
+      accounts = usersData.modules.users.accounts or {};
+      
+      # Extract flakeUrls and convert to modules
+      userFlakeModules = lib.mapAttrsToList (name: user:
+        if (user ? flakeUrl && user.flakeUrl != "") then
+          (builtins.getFlake user.flakeUrl).nixosModules.default
+        else
+          {}
+      ) accounts;
+    in
     lib.nixosSystem {
       inherit system;
 
@@ -37,13 +63,14 @@ let
 
       modules =
         commonModules
+        ++ userFlakeModules
         ++ extraModules
         ++ [
           { networking.hostName = hostName; }
         ];
     };
 
-  # Function to generate a set of hosts
+  # Function to generate a set of hosts based on inventory count and overrides
   mkHostGroup = { prefix, count, system ? "x86_64-linux", extraModules ? [], deviceOverrides ? {} }:
     lib.listToAttrs (map (i: {
       name = "${prefix}${toString i}";
@@ -62,7 +89,7 @@ let
                            then externalFlake.nixosModules.default 
                            else {};
 
-          # Config override module
+          # Config override module (filesystem, users)
           overrideModule = { ... }: 
             let
               # Remove special keys that are not filesystem options

hosts/user-config.nix

@@ -1,5 +1,14 @@
 { pkgs, config, lib, ... }:
+
+# ============================================================================
+# User Configuration Module
+# ============================================================================
+# This module defines the schema for user accounts and handles their creation.
+# It bridges the gap between the data in 'users.nix' and the actual NixOS
+# and Home Manager configuration.
+
 let
+  # Submodule defining the structure of a user account
   userSubmodule = lib.types.submodule {
     options = {
       isNormalUser = lib.mkOption { type = lib.types.bool; default = true; };
@@ -12,6 +21,7 @@ let
       extraImports = lib.mkOption { type = lib.types.listOf lib.types.path; default = []; };
       flakeUrl = lib.mkOption { type = lib.types.str; default = ""; description = "URL of a flake to import Home Manager configuration from (e.g. github:user/dotfiles)."; };
       opensshKeys = lib.mkOption { type = lib.types.listOf lib.types.str; default = []; description = "List of SSH public keys for the user."; };
+      shell = lib.mkOption { type = lib.types.nullOr lib.types.package; default = null; description = "The shell for this user."; };
     };
   };
 in
@@ -19,7 +29,7 @@ in
   options.modules.users = {
     shell = lib.mkOption {
       type = lib.types.package;
-      default = pkgs.zsh;
+      default = pkgs.bash;
       description = "The default shell for users.";
     };
     accounts = lib.mkOption {
@@ -35,6 +45,7 @@ in
   };
 
   config = {
+    # Default enabled users (always present)
     modules.users.enabledUsers = [ "root" "engr-ugaif" ];
 
     # Generate NixOS users
@@ -53,7 +64,7 @@ in
         description = if user.description != null then user.description else lib.mkDefault "";
         openssh.authorizedKeys.keys = user.opensshKeys;
         packages = finalPackages;
-        shell = config.modules.users.shell;
+        shell = if user.shell != null then user.shell else config.modules.users.shell;
       }
     ) enabledAccounts;
     
@@ -68,8 +79,7 @@ in
           enabledAccounts = lib.filterAttrs (name: _: lib.elem name config.modules.users.enabledUsers) config.modules.users.accounts;
         in
         lib.mapAttrs (name: user: { ... }: {
-          imports = user.extraImports ++ [ ../sw/theme.nix ../sw/nvim.nix ] ++
+          imports = user.extraImports ++ [ ../sw/theme.nix ../sw/nvim.nix ];
-            (lib.optional (user.flakeUrl != "") (builtins.getFlake user.flakeUrl).homeManagerModules.default);
           home.username = name;
           home.homeDirectory = if name == "root" then "/root" else "/home/${name}";
           home.stateVersion = "25.11";

inventory.nix

@@ -1,4 +1,22 @@
 {
+  # ============================================================================
+  # Fleet Inventory
+  # ============================================================================
+  # This file defines the types of hosts and their counts. It is used by
+  # hosts/default.nix to generate the full set of NixOS configurations.
+  #
+  # Structure:
+  #   <host-type> = {
+  #     count = <number>;       # Number of hosts to generate (e.g., nix-laptop1, nix-laptop2)
+  #     devices = {             # Per-device overrides
+  #       "<index>" = {
+  #         extraUsers = [ ... ];  # Users enabled on this specific device
+  #         flakeUrl = "...";      # Optional external system flake for full override
+  #         ...                    # Other hardware/filesystem overrides
+  #       };
+  #     };
+  #   };
+
   # Laptop Configuration
   # Base specs: NVMe drive, 34G Swap
   nix-laptop = {

sw/default.nix

@@ -1,5 +1,12 @@
 { config, lib, pkgs, inputs, ... }:
 
+# ============================================================================
+# Software Module Entry Point
+# ============================================================================
+# This module manages the software configuration for the system. It provides
+# options to select the system type ('desktop' or 'kiosk') and handles
+# the conditional importation of the appropriate sub-modules.
+
 with lib;
 
 let
@@ -46,6 +53,7 @@ in
         git
         oh-my-posh
         inputs.lazyvim-nixvim.packages.${stdenv.hostPlatform.system}.nvim
+        # Custom update script
         (writeShellScriptBin "update-system" ''
           HOSTNAME=$(hostname)
           FLAKE_URI="github:UGA-Innovation-Factory/nixos-systems"
@@ -63,6 +71,7 @@ in
         '')
       ];
     }
+    # Import Desktop or Kiosk modules based on type
     (mkIf (cfg.type == "desktop") (import ./desktop { inherit config lib pkgs inputs; }))
     (mkIf (cfg.type == "kiosk") (import ./kiosk { inherit config lib pkgs inputs; }))
   ]);

sw/nvim.nix

@@ -1,5 +1,11 @@
 { pkgs, ... }:
 {
+  # ============================================================================
+  # Neovim Configuration
+  # ============================================================================
+  # This module configures Neovim, specifically setting up TreeSitter parsers
+  # to ensure syntax highlighting works correctly.
+  
   # https://github.com/nvim-treesitter/nvim-treesitter#i-get-query-error-invalid-node-type-at-position
   xdg.configFile."nvim/parser".source =
     let

sw/python.nix

@@ -1,5 +1,12 @@
 { config, lib, pkgs, ... }:
 
+# ============================================================================
+# Python Environment
+# ============================================================================
+# This module provides Python development tools. It installs 'pixi' and 'uv'
+# for project-based dependency management, rather than installing global
+# Python packages which can lead to conflicts.
+
 with lib;
 
 let

sw/theme.nix

@@ -1,5 +1,11 @@
 { pkgs, config, osConfig, lib, ... }:
 
+# ============================================================================
+# Shell Theme Configuration
+# ============================================================================
+# This module configures the shell environment (Zsh, Oh My Posh) for users.
+# It is imported by default for all users to ensure a consistent experience.
+
 let
   # Fetch upstream OMP theme once
   jyumppTheme = pkgs.fetchurl {
@@ -15,11 +21,9 @@ let
 
   isRoot = config.home.username == "root";
   themeFile = if isRoot then jyumppRootTheme else jyumppTheme;
-  
-  isZsh = osConfig.modules.users.shell == pkgs.zsh;
 in
 {
-  config = lib.mkIf isZsh {
+  config = {
     programs.zsh = {
       enable = true;
 

users.nix

@@ -1,5 +1,12 @@
 { pkgs, ... }:
 {
+  # ============================================================================
+  # User Definitions
+  # ============================================================================
+  # This file defines the available user accounts. These accounts are NOT
+  # enabled by default on all systems. They must be enabled via the
+  # 'modules.users.enabledUsers' option in inventory.nix or system flakes.
+
   # Define the users here using the new option
   # To generate a password hash, run: mkpasswd -m sha-512
   modules.users.accounts = {
@@ -17,6 +24,7 @@
       description = "Hunter Halloran";
       extraGroups = [ "networkmanager" "wheel" ];
       homePackages = [ pkgs.ghostty ];
+      shell = pkgs.zsh;
       # Example of using an external flake for configuration:
       # flakeUrl = "github:hdh20267/dotfiles";
     };