From d97ece898c934aee6becdf0b693a91e00d6dfa89 Mon Sep 17 00:00:00 2001
From: Hunter Halloran <hdh20267@uga.edu>
Date: Wed, 17 Dec 2025 19:39:02 -0500
Subject: [PATCH] docs: General documentation update

---
 .github/copilot-instructions.md |  15 ++--
 README.md                       |  13 ++--
 docs/DEVELOPMENT.md             |  15 ++--
 docs/EXTERNAL_MODULES.md        | 132 +++++++++++++++++++++-----------
 docs/NAMESPACE.md               |  18 +++--
 docs/USER_CONFIGURATION.md      |  81 ++++++++++----------
 flake.lock                      |  30 ++++----
 templates/default.nix           |   6 +-
 templates/user/README.md        | 106 +++++++++++++------------
 templates/user/nixos.nix        |   9 +--
 templates/user/user.nix         |  74 ++++++++++--------
 users.nix                       |  11 ++-
 12 files changed, 287 insertions(+), 223 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index acc06de..8eba6b5 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -107,7 +107,7 @@ ugaif.forUser = "username";            # Convenience: enable user + set WSL user
 
 #### Creating External Modules
 1. Use templates: `nix flake init -t github:UGA-Innovation-Factory/nixos-systems#{user|system}`
-2. User modules: Provide `home.nix` (required) and `nixos.nix` (optional)
+2. User modules: Provide `user.nix` (required) and `nixos.nix` (optional)
 3. System modules: Provide `default.nix` that accepts `{ inputs, ... }`
 4. Reference in `inventory.nix` or `users.nix` using `builtins.fetchGit`
 
@@ -135,13 +135,12 @@ This repository supports external configurations via Git repositories:
 ### User Configurations (Dotfiles)
 ```nix
 # In users.nix
-myuser = {
-  description = "My Name";
-  home = builtins.fetchGit {
-    url = "https://github.com/username/dotfiles";
-    rev = "abc123...";  # Pin to specific commit
-  };
+myuser.external = builtins.fetchGit {
+  url = "https://github.com/username/dotfiles";
+  rev = "abc123...";  # Pin to specific commit
 };
+# The external user.nix file contains BOTH user account options
+# (ugaif.users.myuser) AND home-manager configuration
 ```
 
 ### System Configurations
@@ -157,7 +156,7 @@ nix-lxc = {
 
 **Key Points:**
 - External modules receive `{ inputs }` parameter with flake inputs
-- User modules must provide `home.nix` (home-manager config)
+- User modules must provide `user.nix` (user options AND home-manager config)
 - System modules must provide `default.nix` (NixOS module)
 - Always pin to specific commit hash (`rev`) for reproducibility
 
diff --git a/README.md b/README.md
index 46dc5dc..414116f 100644
--- a/README.md
+++ b/README.md
@@ -175,14 +175,13 @@ nix-desktop = {
 Users and systems can reference external Git repositories for configuration:
 
 ```nix
-# In users.nix - External dotfiles
-myuser = {
-  description = "My Name";
-  home = builtins.fetchGit {
-    url = "https://github.com/username/dotfiles";
-    rev = "abc123...";
-  };
+# In users.nix - External dotfiles with user configuration
+myuser.external = builtins.fetchGit {
+  url = "https://github.com/username/dotfiles";
+  rev = "abc123...";
 };
+# The external user.nix file contains both ugaif.users.myuser options
+# AND home-manager configuration
 
 # In inventory.nix - External system config
 nix-lxc = {
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 5644277..5263697 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -305,16 +305,15 @@ nix-laptop = {
 
 ### User-Specific Packages
 
-Add to user's home-manager configuration in `users.nix` or external dotfiles:
+Add to user's home-manager configuration in their external `user.nix`:
 
 ```nix
-myuser = {
-  homePackages = with pkgs; [
-    ripgrep
-    fd
-    bat
-  ];
-};
+# In external user.nix
+home.packages = with pkgs; [
+  ripgrep
+  fd
+  bat
+];
 ```
 
 ### Search for Packages
diff --git a/docs/EXTERNAL_MODULES.md b/docs/EXTERNAL_MODULES.md
index 30a06ff..018ea9c 100644
--- a/docs/EXTERNAL_MODULES.md
+++ b/docs/EXTERNAL_MODULES.md
@@ -109,16 +109,18 @@ External user modules provide home-manager configurations (dotfiles, packages, p
 
 ```nix
 ugaif.users = {
-  myuser = {
-    description = "My Name";
-    extraGroups = [ "wheel" "networkmanager" ];
+  # External user module (dotfiles, home-manager, and user options)
+  myuser = builtins.fetchGit {
+    url = "https://github.com/username/dotfiles";
+    rev = "abc123...";
+  };
+
+  # Inline user definition
+  inlineuser = {
+    description = "Inline User";
+    extraGroups = [ "wheel" ];
+    shell = pkgs.zsh;
     hashedPassword = "$6$...";
-    
-    # External home-manager configuration
-    home = builtins.fetchGit {
-      url = "https://github.com/username/dotfiles";
-      rev = "abc123...";
-    };
   };
 };
 ```
@@ -127,20 +129,35 @@ ugaif.users = {
 
 ```
 dotfiles/
-├── home.nix     # Required: Home-manager config
+├── user.nix     # Required: User options AND home-manager config
 ├── nixos.nix    # Optional: System-level config
-└── dotfiles/    # Optional: Actual dotfiles
+└── config/      # Optional: Actual dotfiles
     ├── bashrc
     └── vimrc
 ```
 
-**home.nix (required):**
+**user.nix (required):**
 ```nix
 { inputs, ... }:
-{ config, lib, pkgs, osConfig, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
 {
-  # Home-manager configuration
-  home.packages = with pkgs; [ vim git htop ];
+  # ========== User Account Configuration ==========
+  ugaif.users.myusername = {
+    description = "Your Full Name";
+    shell = pkgs.zsh;
+    hashedPassword = "!";
+    opensshKeys = [ "ssh-ed25519 AAAA..." ];
+    useZshTheme = true;
+    useNvimPlugins = true;
+  };
+
+  # ========== Home Manager Configuration ==========
+  # Packages
+  home.packages = with pkgs; [
+    vim
+    git
+    htop
+  ] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
   
   programs.git = {
     enable = true;
@@ -166,7 +183,7 @@ dotfiles/
 
 ### What User Modules Receive
 
-**In home.nix:**
+**In user.nix:**
 - **`inputs`** - Flake inputs (nixpkgs, home-manager, etc.)
 - **`config`** - Home-manager configuration
 - **`lib`** - Nixpkgs library functions
@@ -187,8 +204,7 @@ username = {
   description = "Full Name";
   
   # External configuration
-  home = builtins.fetchGit { ... };
-  
+  external = builtins.fetchGit { ... };
   # System settings
   extraGroups = [ "wheel" "networkmanager" ];
   hashedPassword = "$6$...";
@@ -325,16 +341,24 @@ They can use all standard NixOS options plus `ugaif.*` namespace options.
 
 ### User Module Integration
 
-External user modules are loaded separately for home-manager (`home.nix`) and NixOS (`nixos.nix` if it exists):
+External user modules are loaded in two contexts:
 
-**Home-manager:**
+**User options (NixOS module context):**
 ```nix
-import (externalHomePath + "/home.nix") { inherit inputs; }
+import (externalPath + "/user.nix") { inherit inputs; }
+# Evaluated as NixOS module to extract ugaif.users.<username> options
 ```
 
-**NixOS (optional):**
+**Home-manager configuration:**
 ```nix
-import (externalHomePath + "/nixos.nix") { inherit inputs; }
+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
@@ -357,27 +381,21 @@ nix-lxc = {
 };
 ```
 
-## Examples
-
-### Minimal System Module
-
-**default.nix:**
-```nix
-{ inputs, ... }:
-{ config, lib, pkgs, ... }:
-{
-  ugaif.sw.type = "headless";
-  services.nginx.enable = true;
-}
-```
-
 ### Minimal User Module
 
-**home.nix:**
+**user.nix:**
 ```nix
 { inputs, ... }:
-{ config, lib, pkgs, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
 {
+  # User account options
+  ugaif.users.myusername = {
+    description = "My Name";
+    shell = pkgs.zsh;
+    hashedPassword = "!";
+  };
+  
+  # Home-manager config
   home.packages = with pkgs; [ vim git ];
 }
 ```
@@ -386,7 +404,7 @@ nix-lxc = {
 
 ```
 dotfiles/
-├── home.nix
+├── user.nix
 ├── nixos.nix
 └── config/
     ├── bashrc
@@ -394,12 +412,35 @@ dotfiles/
     └── gitconfig
 ```
 
-**home.nix:**
+**user.nix:**
 ```nix
 { inputs, ... }:
-{ config, lib, pkgs, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
 {
-  home.packages = with pkgs; [ ripgrep fd bat ];
+  # User account configuration
+  ugaif.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.ugaif.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;
@@ -411,8 +452,9 @@ dotfiles/
 
 ## See Also
 
-- [docs/INVENTORY.md](INVENTORY.md) - Host configuration guide
-- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options reference
+- [INVENTORY.md](INVENTORY.md) - Host configuration guide
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
+- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
 - [templates/system/](../templates/system/) - System module template
 - [templates/user/](../templates/user/) - User module template
 - [README.md](../README.md) - Main documentation
diff --git a/docs/NAMESPACE.md b/docs/NAMESPACE.md
index 1824e8e..15e86e1 100644
--- a/docs/NAMESPACE.md
+++ b/docs/NAMESPACE.md
@@ -199,6 +199,7 @@ ugaif.users = {
 Each user in `users.nix` can be configured with:
 
 ```nix
+# Option 1: Define inline in users.nix
 ugaif.users.myuser = {
   description = "Full Name";
   isNormalUser = true;                    # Default: true
@@ -206,18 +207,18 @@ ugaif.users.myuser = {
   shell = pkgs.zsh;                       # Login shell
   hashedPassword = "$6$...";              # Hashed password
   opensshKeys = [ "ssh-ed25519 ..." ];    # SSH public keys
-  homePackages = with pkgs; [ ... ];      # User packages
   useZshTheme = true;                     # Use system Zsh theme
   useNvimPlugins = true;                  # Use system Neovim config
   
-  # External home-manager configuration (optional)
-  home = builtins.fetchGit {
-    url = "https://github.com/username/dotfiles";
-    rev = "abc123...";
-  };
-  
   enable = false;  # Enable per-system in inventory.nix
 };
+
+# Option 2: Use external configuration (recommended)
+# The external user.nix can set ugaif.users.myuser options directly
+ugaif.users.anotheruser.external = builtins.fetchGit {
+  url = "https://github.com/username/dotfiles";
+  rev = "abc123...";
+};
 ```
 
 ## System Configuration (`ugaif.system`)
@@ -271,5 +272,6 @@ nix-wsl = {
 ## See Also
 
 - [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide
-- [USER_CONFIGURATION.md](../USER_CONFIGURATION.md) - User management guide
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
 - [README.md](../README.md) - Main documentation
diff --git a/docs/USER_CONFIGURATION.md b/docs/USER_CONFIGURATION.md
index 820ae64..3fb8497 100644
--- a/docs/USER_CONFIGURATION.md
+++ b/docs/USER_CONFIGURATION.md
@@ -27,6 +27,7 @@ Users are defined in `users.nix` but are **not enabled by default** on all syste
 
 ```nix
 ugaif.users = {
+  # Option 1: Inline definition
   myuser = {
     description = "My Full Name";
     extraGroups = [ "wheel" "networkmanager" ];
@@ -36,6 +37,12 @@ ugaif.users = {
       "ssh-ed25519 AAAA... user@machine"
     ];
   };
+  
+  # Option 2: External configuration (recommended for personalization)
+  myuser.external = builtins.fetchGit {
+    url = "https://github.com/username/dotfiles";
+    rev = "abc123...";  # Pin to specific commit
+  };
 };
 ```
 
@@ -93,14 +100,6 @@ username = {
   # === External Configuration ===
   external = builtins.fetchGit { ... };   # External user module (see below)
   
-  # OR (if not using external config):
-  homePackages = with pkgs; [             # User packages
-    ripgrep
-    fd
-    bat
-  ];
-  extraImports = [ ./my-module.nix ];     # Additional home-manager modules
-  
   # === Theme Integration ===
   useZshTheme = true;                     # Apply system Zsh theme (default: true)
   useNvimPlugins = true;                  # Apply system Neovim config (default: true)
@@ -137,7 +136,7 @@ myuser = {
 
 ```
 dotfiles/
-├── user.nix     # Optional: User options AND home-manager config
+├── user.nix     # Required: User options AND home-manager config
 ├── nixos.nix    # Optional: System-level configuration
 └── config/      # Optional: Your dotfiles
     ├── bashrc
@@ -145,32 +144,42 @@ dotfiles/
     └── ...
 ```
 
-**Both `.nix` files are optional, but at least one should be present.**
+**At least `user.nix` should be present for a functional user module.**
 
-**user.nix (optional):**
+**user.nix (required):**
 ```nix
 { inputs, ... }:
-{ config, lib, pkgs, ... }:
-
+{ config, lib, pkgs, osConfig ? null, ... }:
 {
-  # User account options (imported as NixOS module)
+  # ========== User Account Configuration ==========
+  # These options define the user account itself
   ugaif.users.myuser = {
     description = "My Full Name";
     extraGroups = [ "wheel" "docker" ];
     shell = pkgs.zsh;
+    hashedPassword = "!";
+    opensshKeys = [
+      "ssh-ed25519 AAAA... user@host"
+    ];
     useZshTheme = true;
+    useNvimPlugins = true;
   };
 
-  # Home-manager configuration (imported into home-manager)
+  # ========== Home Manager Configuration ==========
+  # User environment, packages, and dotfiles
+  
   home.packages = with pkgs; [
     vim
     ripgrep
-  ];
+  ] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
 
   programs.git = {
     enable = true;
     userName = "My Name";
     userEmail = "me@example.com";
+    extraConfig = {
+      init.defaultBranch = "main";
+    };
   };
   
   home.file.".bashrc".source = ./config/bashrc;
@@ -199,13 +208,15 @@ dotfiles/
 
 ### How External Modules Are Loaded
 
-The `user.nix` module is used in two ways:
+The `user.nix` module serves a dual purpose and is imported in **two contexts**:
 
-1. **User Options (Data Extraction)**: The `ugaif.users.<username>` options are extracted and loaded as **data**. The module is evaluated with minimal arguments to extract just the ugaif.users options, which override any defaults set in `users.nix` (which uses `lib.mkDefault`).
+1. **NixOS Module Context (User Options)**: The module is imported as a NixOS module where `ugaif.users.<username>` options are read to define the user account (description, shell, groups, SSH keys, etc.). These options override any defaults set in `users.nix`.
 
-2. **Home-Manager Configuration**: The entire module (including `home.*`, `programs.*`, `services.*` options) is imported into home-manager as a configuration module.
+2. **Home-Manager Context**: The same module is imported into home-manager where `home.*`, `programs.*`, and `services.*` options configure the user's environment, packages, and dotfiles.
 
-This means you can define both user account settings AND home-manager configuration in a single file.
+**Key insight:** A single `user.nix` file contains both account configuration AND home environment configuration. The system automatically imports it in the appropriate contexts.
+
+**Example:** The user account options (like `shell`, `extraGroups`) are read during NixOS evaluation, while home-manager options (like `home.packages`, `programs.git`) are used when building the user's home environment.
 
 **In nixos.nix:**
 - `inputs` - Flake inputs
@@ -220,17 +231,7 @@ This means you can define both user account settings AND home-manager configurat
 external = /home/username/dev/dotfiles;
 ```
 
-**Note:** User options can be set in users.nix OR in the external module's user.nix file.
-
-**No external config:**
-```nix
-# Configure everything directly in users.nix
-myuser = {
-  description = "My Name";
-  homePackages = with pkgs; [ vim git ];
-  # external is null by default
-};
-```
+**Note:** User options can be set in users.nix OR in the external module's user.nix file. For custom packages and environment configuration without external modules, create a local module and reference it with `extraImports`.
 
 ### Create User Template
 
@@ -380,7 +381,7 @@ admin = {
 };
 ```
 
-### User with External Dotfiles
+### User with External Configuration
 
 ```nix
 developer = {
@@ -388,7 +389,7 @@ developer = {
   extraGroups = [ "wheel" "docker" ];
   shell = pkgs.zsh;
   hashedPassword = "$6$...";
-  home = builtins.fetchGit {
+  external = builtins.fetchGit {
     url = "https://github.com/username/dotfiles";
     rev = "abc123def456...";
   };
@@ -403,7 +404,7 @@ wsl-user = {
   extraGroups = [ "wheel" ];
   shell = pkgs.zsh;
   hashedPassword = "$6$...";
-  home = builtins.fetchGit {
+  external = builtins.fetchGit {
     url = "https://github.com/username/dotfiles";
     rev = "abc123...";
   };
@@ -429,7 +430,7 @@ poweruser = {
   hashedPassword = "$6$...";
   useZshTheme = false;      # Don't apply system theme
   useNvimPlugins = false;   # Don't apply system nvim config
-  home = builtins.fetchGit {
+  external = builtins.fetchGit {
     url = "https://github.com/username/custom-dotfiles";
     rev = "abc123...";
   };
@@ -492,19 +493,19 @@ git ls-remote https://github.com/username/dotfiles
 ```
 
 **Verify structure:**
-- Must have `home.nix` at repository root
+- Must have `user.nix` at repository root
 - `nixos.nix` is optional
 - Check file permissions
 
 **Test with local path first:**
 ```nix
-home = /path/to/local/dotfiles;
+external = /path/to/local/dotfiles;
 ```
 
 ## See Also
 
-- [docs/EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide
-- [docs/INVENTORY.md](INVENTORY.md) - Host configuration
-- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide
+- [INVENTORY.md](INVENTORY.md) - Host configuration guide
+- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
 - [templates/user/](../templates/user/) - User module template
 - [README.md](../README.md) - Main documentation
diff --git a/flake.lock b/flake.lock
index c799bdb..40db052 100644
--- a/flake.lock
+++ b/flake.lock
@@ -115,11 +115,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1765326679,
-        "narHash": "sha256-fTLX9kDwLr9Y0rH/nG+h1XG5UU+jBcy0PFYn5eneRX8=",
+        "lastModified": 1765794845,
+        "narHash": "sha256-YD5QWlGnusNbZCqR3pxG8tRxx9yUXayLZfAJRWspq2s=",
         "owner": "nix-community",
         "repo": "disko",
-        "rev": "d64e5cdca35b5fad7c504f615357a7afe6d9c49e",
+        "rev": "7194cfe5b7a3660726b0fe7296070eaef601cae9",
         "type": "github"
       },
       "original": {
@@ -318,11 +318,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1765384171,
-        "narHash": "sha256-FuFtkJrW1Z7u+3lhzPRau69E0CNjADku1mLQQflUORo=",
+        "lastModified": 1765979862,
+        "narHash": "sha256-/r9/1KamvbHJx6I40H4HsSXnEcBAkj46ZwibhBx9kg0=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "44777152652bc9eacf8876976fa72cc77ca8b9d8",
+        "rev": "d3135ab747fd9dac250ffb90b4a7e80634eacbe9",
         "type": "github"
       },
       "original": {
@@ -486,11 +486,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1765483419,
-        "narHash": "sha256-w6wznH1lBzlSH3+pWDkE+L6xA0F02drFAzu2E7PD/Jo=",
+        "lastModified": 1765841014,
+        "narHash": "sha256-55V0AJ36V5Egh4kMhWtDh117eE3GOjwq5LhwxDn9eHg=",
         "owner": "nix-community",
         "repo": "NixOS-WSL",
-        "rev": "0c040f28b44b18e0d4240e027096078e34dbb029",
+        "rev": "be4af8042e7a61fa12fda58fe9a3b3babdefe17b",
         "type": "github"
       },
       "original": {
@@ -518,11 +518,11 @@
     },
     "nixpkgs-old-kernel": {
       "locked": {
-        "lastModified": 1764939437,
-        "narHash": "sha256-4TLFHUwXraw9Df5mXC/vCrJgb50CRr3CzUzF0Mn3CII=",
+        "lastModified": 1765687488,
+        "narHash": "sha256-7YAJ6xgBAQ/Nr+7MI13Tui1ULflgAdKh63m1tfYV7+M=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "00d2457e2f608b4be6fe8b470b0a36816324b0ae",
+        "rev": "d02bcc33948ca19b0aaa0213fe987ceec1f4ebe1",
         "type": "github"
       },
       "original": {
@@ -534,11 +534,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1765311797,
-        "narHash": "sha256-mSD5Ob7a+T2RNjvPvOA1dkJHGVrNVl8ZOrAwBjKBDQo=",
+        "lastModified": 1765838191,
+        "narHash": "sha256-m5KWt1nOm76ILk/JSCxBM4MfK3rYY7Wq9/TZIIeGnT8=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "09eb77e94fa25202af8f3e81ddc7353d9970ac1b",
+        "rev": "c6f52ebd45e5925c188d1a20119978aa4ffd5ef6",
         "type": "github"
       },
       "original": {
diff --git a/templates/default.nix b/templates/default.nix
index 8b628e7..ce2dee1 100644
--- a/templates/default.nix
+++ b/templates/default.nix
@@ -20,7 +20,7 @@
 
   user = {
     path = ./user;
-    description = "External user home-manager configuration";
+    description = "External user configuration module";
     welcomeText = ''
       # User Configuration Template
 
@@ -29,10 +29,10 @@
 
       ## Quick Start
 
-      1. Edit `home.nix` with your home-manager configuration
+      1. Edit `user.nix` with user account options and home-manager configuration
       2. (Optional) Edit `nixos.nix` for system-level configuration
       3. Commit to a Git repository
-      4. Reference in users.nix using the `flakeUrl` field
+      4. Reference in users.nix using external = builtins.fetchGit { ... }
 
       See README.md for detailed documentation.
     '';
diff --git a/templates/user/README.md b/templates/user/README.md
index bd1934e..74799e7 100644
--- a/templates/user/README.md
+++ b/templates/user/README.md
@@ -10,46 +10,47 @@ External user modules allow users to maintain their personal configurations (dot
 
 ```
 user-dotfiles-repo/
-├── user.nix          # Optional: User options AND home-manager configuration
+├── user.nix          # Required: User options AND home-manager configuration
 ├── nixos.nix         # Optional: System-level NixOS configuration
 ├── README.md         # Documentation
-└── dotfiles/         # Optional: Dotfiles to symlink
+└── config/           # Optional: Dotfiles to symlink
+    ├── bashrc
+    └── vimrc
 ```
 
-**Note:** Both `.nix` files are optional, but at least one should be present for the module to be useful.
+**Note:** The `user.nix` file is required for a functional user module. It should contain both `ugaif.users.<username>` options and home-manager configuration.
 
 ## Usage
 
 ### 1. Create Your User Configuration Repository
 
 Copy the templates from this directory to your own Git repository:
-- `home.nix` - Required for home-manager configuration
-- `nixos.nix` - Optional for system-level configuration
+- `user.nix` - Required: Contains both user account options and home-manager configuration
+- `nixos.nix` - Optional: System-level NixOS configuration (e.g., system services, extra groups)
 
 ### 2. Reference It in users.nix
 
 ```nix
 {
   ugaif.users = {
-    myusername = {
-      # Option 1: Set user options in users.nix
+    # Option 1: Define inline (without external module)
+    inlineuser = {
       description = "My Name";
       extraGroups = [ "wheel" "networkmanager" ];
       shell = pkgs.zsh;
-      
-      # Option 2: Or let the external module's user.nix set these options
-      
-      # Reference external dotfiles module
-      external = builtins.fetchGit {
-        url = "https://github.com/username/dotfiles";
-        rev = "abc123def456...";  # Full commit hash for reproducibility
-        ref = "main";              # Optional: branch/tag name
-      };
-      
-      # Or use local path for testing
-      # external = /path/to/local/dotfiles;
-      # };
+      hashedPassword = "$6$...";
     };
+    
+    # Option 2: Use external module (recommended for personal configs)
+    # The external user.nix will set ugaif.users.myusername options
+    myusername.external = builtins.fetchGit {
+      url = "https://github.com/username/dotfiles";
+      rev = "abc123def456...";  # Full commit hash for reproducibility
+      ref = "main";              # Optional: branch/tag name
+    };
+    
+    # Or use local path for testing
+    # myusername.external = /path/to/local/dotfiles;
   };
 }
 ```
@@ -72,30 +73,26 @@ Enable the user in `inventory.nix`:
 
 ## File Descriptions
 
-### user.nix (Optional)
+### user.nix (Required)
 
-This file serves dual purpose:
-1. Sets `ugaif.users.<username>` options (description, shell, extraGroups, etc.)
-2. Provides home-manager configuration (programs.*, home.*, services.*)
+This file serves a dual purpose and is imported in **two contexts**:
+
+1. **NixOS Module Context**: Imported to read `ugaif.users.<username>` options that define the user account (description, shell, groups, SSH keys, etc.)
+2. **Home-Manager Context**: Imported to configure the user environment with `home.*`, `programs.*`, and `services.*` options
 
 **How it works:**
-- The `ugaif.users.<username>` options are extracted and loaded as **data** during module evaluation
-- These options override any defaults set in `users.nix` (which uses `lib.mkDefault`)
-- The home-manager options (`home.*`, `programs.*`, etc.) are imported as a module for home-manager
-- External module options take precedence over `users.nix` base configuration
-
-The same file is imported in two contexts:
-- As a NixOS module to read ugaif.users options
-- As a home-manager module for home.*, programs.*, services.*, etc.
-
-Simply include both types of options in the same file.
+- The same file is evaluated twice in different contexts
+- User account options (`ugaif.users.<username>`) are read during NixOS evaluation
+- Home-manager options are used when building the user's environment
+- External module options override any defaults set in `users.nix`
+- You can conditionally include packages/config based on system type using `osConfig`
 
 **Receives:**
 - `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
-- `config` - Config (NixOS or home-manager depending on context)
-- `lib` - Nixpkgs library
+- `config` - Configuration (NixOS or home-manager depending on context)
+- `lib` - Nixpkgs library functions
 - `pkgs` - Nixpkgs package set
-- `osConfig` - (home-manager context only) OS-level configuration
+- `osConfig` - (home-manager context only) Read-only access to OS configuration
 
 **Example:** See `user.nix` template
 
@@ -118,17 +115,20 @@ This file contains system-level NixOS configuration. Only needed for:
 
 ```nix
 { inputs, ... }:
-{ config, lib, pkgs, ... }:
-
+{ config, lib, pkgs, osConfig ? null, ... }:
 {
-  # User account options (imported as NixOS module)
+  # User account options
   ugaif.users.myuser = {
     description = "My Name";
     shell = pkgs.zsh;
+    hashedPassword = "!";
     extraGroups = [ "wheel" "networkmanager" ];
+    opensshKeys = [ "ssh-ed25519 AAAA... user@host" ];
+    useZshTheme = true;
+    useNvimPlugins = true;
   };
 
-  # Home-manager configuration (imported into home-manager)
+  # Home-manager configuration
   home.packages = with pkgs; [
     vim
     git
@@ -139,6 +139,7 @@ This file contains system-level NixOS configuration. Only needed for:
     enable = true;
     userName = "My Name";
     userEmail = "me@example.com";
+    extraConfig.init.defaultBranch = "main";
   };
 }
 ```
@@ -147,24 +148,31 @@ This file contains system-level NixOS configuration. Only needed for:
 
 ```nix
 { inputs, ... }:
-{ config, lib, pkgs, ... }:
-
+{ config, lib, pkgs, osConfig ? null, ... }:
 {
   ugaif.users.myuser = {
     description = "My Name";
     shell = pkgs.zsh;
+    hashedPassword = "!";
+    extraGroups = [ "wheel" ];
+    opensshKeys = [ "ssh-ed25519 AAAA..." ];
   };
 
-  home.packages = with pkgs; [ ripgrep fd bat ];
+  home.packages = with pkgs; [
+    ripgrep
+    fd
+    bat
+  ] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
 
   # Symlink dotfiles
-  home.file.".bashrc".source = ./dotfiles/bashrc;
-  home.file.".vimrc".source = ./dotfiles/vimrc;
+  home.file.".bashrc".source = ./config/bashrc;
+  home.file.".vimrc".source = ./config/vimrc;
   
   programs.git = {
     enable = true;
     userName = "My Name";
     userEmail = "me@example.com";
+    extraConfig.init.defaultBranch = "main";
   };
 }
 ```
@@ -189,11 +197,13 @@ This file contains system-level NixOS configuration. Only needed for:
 
 External user modules:
 - Receive the same flake inputs as nixos-systems
-- Can set user options via user.nix (description, shell, home-manager, etc.)
+- Define both user account options AND home-manager config in user.nix
+- Single file is imported in two contexts (NixOS module + home-manager module)
+- Can access OS configuration via `osConfig` parameter in home-manager context
 - Optionally provide system-level configuration (nixos.nix)
 - System zsh theme applied if `useZshTheme = true` (default)
 - System nvim config applied if `useNvimPlugins = true` (default)
-- Settings from user.nix override base users.nix definitions
+- Settings from external user.nix override base users.nix definitions
 
 ## Development Workflow
 
diff --git a/templates/user/nixos.nix b/templates/user/nixos.nix
index b38080c..2a2868d 100644
--- a/templates/user/nixos.nix
+++ b/templates/user/nixos.nix
@@ -4,16 +4,15 @@
 # User NixOS System Configuration (Optional)
 # ============================================================================
 # This file provides system-level NixOS configuration for a user.
-# It's optional - most user configuration should go in home.nix.
+# It's optional - most user configuration should go in user.nix.
 #
 # Use this for:
 # - System-level services that depend on the user (e.g., user systemd services)
 # - Special system permissions or configurations
 # - Installing system packages that require root
 #
-# Note: User options (description, shell, extraGroups, etc.) should be set
-# in your external module's user.nix or in the main users.nix file, not in
-# this nixos.nix.
+# Note: User options (description, shell, extraGroups, etc.) AND home-manager
+# configuration should be set in user.nix, not in this nixos.nix.
 #
 # This module receives the same `inputs` flake inputs as the main
 # nixos-systems configuration.
@@ -47,5 +46,5 @@
   # Example: Add user to additional groups
   # users.users.myusername.extraGroups = [ "docker" ];
 
-  # Most configuration should be in home.nix instead of here
+  # Most configuration should be in user.nix instead of here
 }
diff --git a/templates/user/user.nix b/templates/user/user.nix
index 2fee065..707c8b9 100644
--- a/templates/user/user.nix
+++ b/templates/user/user.nix
@@ -1,16 +1,15 @@
 { inputs, ... }:
 
 # ============================================================================
-# User Configuration (Optional)
+# User Configuration
 # ============================================================================
-# This file can configure BOTH:
-# 1. User account options (ugaif.users.<username>) when imported as NixOS module
-# 2. Home-manager configuration (home.*, programs.*, services.*) when imported
-#    into home-manager
+# This file configures BOTH:
+# 1. User account options (ugaif.users.<username>)
+# 2. Home-manager configuration (home.*, programs.*, services.*)
 #
-# This file is optional - if not present, the system will use the defaults
-# from the main users.nix file. Use this file to override or extend those
-# default user and home-manager options for this user.
+# The same file is imported in two contexts:
+# - As a NixOS module to read ugaif.users.<username> options
+# - As a home-manager module for user environment configuration
 #
 # This module receives the same `inputs` flake inputs as the main
 # nixos-systems configuration (nixpkgs, home-manager, etc.).
@@ -25,45 +24,44 @@
 
 {
   # ========== User Account Configuration ==========
-  # These are imported as a NixOS module to set ugaif.users options
   # Replace "myusername" with your actual username
 
   ugaif.users.myusername = {
     description = "Your Full Name";
+    shell = pkgs.zsh;
+    hashedPassword = "!"; # Locked password - use SSH keys only
 
     extraGroups = [
       "wheel" # Sudo access
       "networkmanager" # Network configuration
-      # "docker"         # Docker access (if needed)
+      # "docker"       # Docker access (if needed)
     ];
 
-    shell = pkgs.zsh;
+    opensshKeys = [
+      # Add your SSH public keys here
+      # "ssh-ed25519 AAAA... user@machine"
+    ];
 
-    # Optional: Override editor
-    # editor = pkgs.helix;
-
-    # Optional: Disable system theme/nvim plugins
-    # useZshTheme = false;
-    # useNvimPlugins = false;
-
-    # Optional: Add system-level packages
-    # extraPackages = with pkgs; [ docker ];
+    useZshTheme = true; # Apply system Zsh theme
+    useNvimPlugins = true; # Apply system Neovim plugins
   };
 
   # Note: You don't need to set 'enable = true' - that's controlled
-  # per-host in inventory.nix
+  # per-host in inventory.nix via ugaif.users.myusername.enable
 
   # ========== Home Manager Configuration ==========
-  # These are imported into home-manager for user environment
-  # System theme (zsh) and nvim config are applied automatically based on flags above
 
   # Packages
-  home.packages = with pkgs; [
-    # Add your preferred packages here
-    # ripgrep
-    # fd
-    # bat
-  ];
+  home.packages =
+    with pkgs;
+    [
+      htop
+      ripgrep
+      fd
+      bat
+    ]
+    ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
+  # Conditionally add packages based on system type
 
   # ========== Programs ==========
 
@@ -77,18 +75,28 @@
     };
   };
 
+  # Zsh configuration
+  programs.zsh = {
+    enable = true;
+    # System theme is applied automatically if useZshTheme = true
+  };
+
   # ========== Shell Environment ==========
 
   home.sessionVariables = {
-    # EDITOR is set automatically based on ugaif.users.*.editor
+    EDITOR = "nvim";
     # Add your custom environment variables here
   };
 
+  # ========== XDG Configuration ==========
+
+  xdg.enable = true;
+
   # ========== Dotfiles ==========
 
   # You can manage dotfiles with home.file
-  # home.file.".bashrc".source = ./dotfiles/bashrc;
-  # home.file.".vimrc".source = ./dotfiles/vimrc;
+  # home.file.".bashrc".source = ./config/bashrc;
+  # home.file.".vimrc".source = ./config/vimrc;
 
-  # Or use programs.* options for better integration
+  # Or use programs.* options for better integration (recommended)
 }
diff --git a/users.nix b/users.nix
index 63e5fc3..7571038 100644
--- a/users.nix
+++ b/users.nix
@@ -16,11 +16,16 @@
   #   external = builtins.fetchGit { url = "..."; rev = "..."; };
   #   external = /path/to/local/config;
   #
-  # External repositories can contain:
-  #   - user.nix (optional): Sets ugaif.users.<name> options AND home-manager config
+  # External repositories should contain:
+  #   - user.nix (required): Defines ugaif.users.<name> options AND home-manager config
   #   - nixos.nix (optional): System-level NixOS configuration
   #
-  # User options can be set either in users.nix OR in the external module's user.nix.
+  # The user.nix file is imported in TWO contexts:
+  #   1. As a NixOS module to read ugaif.users.<name> options (account settings)
+  #   2. As a home-manager module for home.*, programs.*, services.* (user environment)
+  #
+  # User options can be set in users.nix OR in the external module's user.nix.
+  # External module options take precedence over users.nix defaults.
   ugaif.users = {
     root = {
       isNormalUser = false;