refactor: Move sw into properly nested modules with unconditional import

fleet/fleet-option.nix

@@ -1,8 +1,8 @@
 # ============================================================================
 # Fleet Option Definition
 # ============================================================================
-# This module only defines the athenix.fleet option without any dependencies.
-# Used by fleet/default.nix to evaluate inventory data without circular dependencies.
+# This module defines the athenix.fleet and athenix.hwTypes options.
+# Self-contained fleet management without dependencies on user configuration.
 { inputs, lib, ... }:
 let
   fleetDefinition = lib.mkOption {
@@ -59,40 +59,67 @@ let
       )
     );
   };
-  # Submodule defining the structure of a user account
+
+  # Forward declaration for user options (full definition in user-config.nix)
+  # This allows users.nix to be evaluated at flake level
   userSubmodule = lib.types.submodule {
     options = {
+      enable = lib.mkOption {
+        type = lib.types.bool;
+        default = false;
+        description = "Whether this user account is enabled on this system.";
+      };
       isNormalUser = lib.mkOption {
         type = lib.types.bool;
         default = true;
+        description = "Whether this is a normal user account (vs system user).";
       };
       description = lib.mkOption {
         type = lib.types.nullOr lib.types.str;
         default = null;
+        description = "Full name or description of the user (GECOS field).";
+        example = "John Doe";
       };
       extraGroups = lib.mkOption {
         type = lib.types.listOf lib.types.str;
         default = [ ];
+        description = "Additional groups for the user (wheel, docker, etc.).";
+        example = [
+          "wheel"
+          "networkmanager"
+          "docker"
+        ];
       };
       hashedPassword = lib.mkOption {
         type = lib.types.str;
         default = "!";
+        description = ''
+          Hashed password for the user account.
+          Generate with: mkpasswd -m sha-512
+          Default "!" means account is locked (SSH key only).
+        '';
       };
       extraPackages = lib.mkOption {
         type = lib.types.listOf lib.types.package;
         default = [ ];
+        description = "Additional system packages available to this user.";
+        example = lib.literalExpression "[ pkgs.vim pkgs.git ]";
       };
       excludePackages = lib.mkOption {
         type = lib.types.listOf lib.types.package;
         default = [ ];
+        description = "System packages to exclude for this user.";
       };
       homePackages = lib.mkOption {
         type = lib.types.listOf lib.types.package;
         default = [ ];
+        description = "Packages to install in the user's home-manager profile.";
+        example = lib.literalExpression "[ pkgs.firefox pkgs.vscode ]";
       };
       extraImports = lib.mkOption {
         type = lib.types.listOf lib.types.path;
         default = [ ];
+        description = "Additional home-manager modules to import for this user.";
       };
       external = lib.mkOption {
         type = lib.types.nullOr (
@@ -104,21 +131,22 @@ let
         );
         default = null;
         description = ''
-          External user configuration module. Can be:
-          - A path to a local module directory
-          - A fetchGit/fetchTarball result pointing to a repository
+          External user configuration module from Git or local path.
 
-          The external module can contain:
-          - user.nix (optional): Sets athenix.users.<name> options AND home-manager config
-          - nixos.nix (optional): System-level NixOS configuration
-
-          Example: builtins.fetchGit { url = "https://github.com/user/dotfiles"; rev = "..."; }
+          Should contain user.nix (user options + home-manager config)
+          and optionally nixos.nix (system-level config).
         '';
+        example = lib.literalExpression ''
+          builtins.fetchGit {
+                    url = "https://github.com/username/dotfiles";
+                    rev = "abc123...";
+                  }'';
       };
       opensshKeys = lib.mkOption {
         type = lib.types.listOf lib.types.str;
         default = [ ];
-        description = "List of SSH public keys for the user.";
+        description = "SSH public keys for the user (authorized_keys).";
+        example = [ "ssh-ed25519 AAAAC3Nza... user@host" ];
       };
       shell = lib.mkOption {
         type = lib.types.nullOr (
@@ -130,7 +158,7 @@ let
           ]
         );
         default = "bash";
-        description = "The shell for this user.";
+        description = "Default shell for the user.";
       };
       editor = lib.mkOption {
         type = lib.types.nullOr (
@@ -143,23 +171,18 @@ let
           ]
         );
         default = "neovim";
-        description = "The default editor for this user.";
+        description = "Default text editor for the user (sets EDITOR).";
       };
       useZshTheme = lib.mkOption {
         type = lib.types.bool;
         default = true;
-        description = "Whether to apply the system Zsh theme.";
+        description = "Whether to apply the system Zsh theme (Oh My Posh).";
       };
       useNvimPlugins = lib.mkOption {
         type = lib.types.bool;
         default = true;
         description = "Whether to apply the system Neovim configuration.";
       };
-      enable = lib.mkOption {
-        type = lib.types.bool;
-        default = false;
-        description = "Whether this user account is enabled on this system.";
-      };
     };
   };
 in