feat: Add templates for external configs

templates/default.nix

@@ -0,0 +1,40 @@
+{
+  system = {
+    path = ./system;
+    description = "External NixOS system configuration module";
+    welcomeText = ''
+      # External System Configuration Template
+
+      This template creates an external NixOS system configuration module
+      that can be referenced from nixos-systems/inventory.nix.
+
+      ## Quick Start
+
+      1. Edit `default.nix` with your system configuration
+      2. Commit to a Git repository
+      3. Reference in inventory.nix using the `flakeUrl` field
+
+      See README.md for detailed documentation.
+    '';
+  };
+
+  user = {
+    path = ./user;
+    description = "External user home-manager configuration";
+    welcomeText = ''
+      # User Configuration Template
+
+      This template creates an external user configuration module
+      that can be referenced from nixos-systems/users.nix.
+
+      ## Quick Start
+
+      1. Edit `home.nix` with your 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
+
+      See README.md for detailed documentation.
+    '';
+  };
+}

templates/system/.gitignore

@@ -0,0 +1,3 @@
+result
+result-*
+.direnv/

templates/system/README.md

@@ -0,0 +1,99 @@
+# External System Module Template
+
+This directory contains a template for creating external system configuration modules that can be referenced from the main `nixos-systems` repository.
+
+## Overview
+
+External modules allow you to maintain system configurations in separate Git repositories and reference them from the main `nixos-systems/inventory.nix` file using `builtins.fetchGit` or `builtins.fetchTarball`.
+
+## Usage
+
+### 1. Create Your Module Repository
+
+Copy `default.nix` from this template to your own Git repository. Customize it with your system configuration.
+
+### 2. Reference It in inventory.nix
+
+```nix
+{
+  "my-system-type" = {
+    devices = {
+      "hostname" = builtins.fetchGit {
+        url = "https://github.com/your-org/your-config-repo";
+        rev = "abc123def456...";  # Full commit hash for reproducibility
+        ref = "main";              # Optional: branch/tag name
+      };
+    };
+  };
+}
+```
+
+### 3. Module Structure
+
+Your `default.nix` must:
+- Accept `{ inputs, ... }` as parameters (you'll receive the same flake inputs)
+- Return a valid NixOS module with `{ config, lib, pkgs, ... }: { ... }`
+- Export configuration under the `config` attribute
+
+## Examples
+
+### Simple Configuration Module
+
+```nix
+{ inputs, ... }:
+
+{ config, lib, pkgs, ... }:
+
+{
+  config = {
+    time.timeZone = "America/New_York";
+    
+    environment.systemPackages = with pkgs; [
+      vim
+      git
+      htop
+    ];
+    
+    services.openssh.enable = true;
+  };
+}
+```
+
+### Advanced Module with Options
+
+```nix
+{ inputs, ... }:
+
+{ config, lib, pkgs, ... }:
+
+{
+  options.myorg.databaseUrl = lib.mkOption {
+    type = lib.types.str;
+    description = "Database connection URL";
+  };
+
+  config = {
+    # Use the option
+    services.postgresql = {
+      enable = true;
+      # ... configuration using config.myorg.databaseUrl
+    };
+  };
+}
+```
+
+## Benefits
+
+- **Separation of Concerns**: Keep specialized configurations in dedicated repositories
+- **Reusability**: Share configurations across multiple NixOS fleets
+- **Version Control**: Pin to specific commits for reproducibility
+- **Team Ownership**: Different teams can maintain their own config repos
+- **Security**: Private repositories for sensitive configurations
+
+## Integration with nixos-systems
+
+External modules are automatically integrated into the nixos-systems build:
+- They receive the same flake inputs (nixpkgs, home-manager, etc.)
+- They can use ugaif.* options if defined in the host type
+- They are merged with local overrides and base configuration
+- They work with all build methods (ISO, LXC, Proxmox, etc.)

templates/system/default.nix

@@ -0,0 +1,56 @@
+{ inputs, ... }:
+
+# ============================================================================
+# External System Module Template
+# ============================================================================
+# This is a template for creating external system configuration modules
+# that can be referenced from nixos-systems/inventory.nix using builtins.fetchGit
+#
+# Usage in inventory.nix:
+#   "my-type" = {
+#     devices = {
+#       "hostname" = builtins.fetchGit {
+#         url = "https://github.com/your-org/your-config-repo";
+#         rev = "commit-hash";
+#       };
+#     };
+#   };
+#
+# This module will receive the same `inputs` flake inputs as the main
+# nixos-systems configuration, allowing you to use nixpkgs, home-manager, etc.
+
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+{
+  # ========== Module Options ==========
+  # Define any custom options your module needs
+  options = {
+    # Example: myorg.customOption = lib.mkOption { ... };
+  };
+
+  # ========== Module Configuration ==========
+  config = {
+    # Your system configuration goes here
+    # This can include any NixOS options
+
+    # Example: Set timezone
+    # time.timeZone = "America/New_York";
+
+    # Example: Install packages
+    # environment.systemPackages = with pkgs; [
+    #   vim
+    #   git
+    # ];
+
+    # Example: Configure services
+    # services.openssh.enable = true;
+
+    # Example: Use ugaif options if available from nixos-systems
+    # ugaif.users.myuser.enable = true;
+  };
+}

templates/user/.gitignore

@@ -0,0 +1,3 @@
+result
+result-*
+.direnv/

templates/user/README.md

@@ -0,0 +1,183 @@
+# User Configuration Template
+
+This directory contains templates for creating external user configuration modules that can be referenced from the main `nixos-systems/users.nix` file.
+
+## Overview
+
+External user modules allow users to maintain their personal configurations (dotfiles, packages, settings) in separate Git repositories and reference them from the main `nixos-systems` repository using `builtins.fetchGit`.
+
+## Structure
+
+```
+user-dotfiles-repo/
+├── home.nix          # Required: Home-manager configuration
+├── nixos.nix         # Optional: System-level NixOS configuration
+├── README.md         # Documentation
+└── dotfiles/         # Optional: Dotfiles to symlink
+```
+
+## 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
+
+### 2. Reference It in users.nix
+
+```nix
+{
+  ugaif.users = {
+    myusername = {
+      description = "My Name";
+      extraGroups = [ "wheel" "networkmanager" ];
+      shell = pkgs.zsh;
+      
+      # Option 1: External module from Git
+      home = builtins.fetchGit {
+        url = "https://github.com/username/dotfiles";
+        rev = "abc123def456...";  # Full commit hash for reproducibility
+        ref = "main";              # Optional: branch/tag name
+      };
+      
+      # Option 2: Local path for testing
+      # home = /path/to/local/dotfiles;
+      
+      # Option 3: Inline configuration
+      # home = {
+      #   home.packages = [ pkgs.vim ];
+      #   programs.git.enable = true;
+      # };
+    };
+  };
+}
+```
+
+### 3. Enable on Systems
+
+Enable the user in `inventory.nix`:
+
+```nix
+{
+  "my-system" = {
+    devices = {
+      "hostname" = {
+        extraUsers = [ "myusername" ];
+      };
+    };
+  };
+}
+```
+
+## File Descriptions
+
+### home.nix (Required)
+
+This file contains your home-manager configuration. It must be a valid NixOS module that accepts `{ inputs, ... }` and returns a home-manager configuration.
+
+**Must export:**
+- Home-manager options (programs.*, home.packages, etc.)
+
+**Receives:**
+- `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
+- `config` - Home-manager config
+- `pkgs` - Nixpkgs package set
+- `osConfig` - Access to OS-level configuration
+
+### nixos.nix (Optional)
+
+This file contains system-level NixOS configuration. Only needed for:
+- System services related to the user
+- System packages requiring root
+- Special permissions or system settings
+
+## Examples
+
+### Minimal home.nix
+
+```nix
+{ inputs, ... }:
+
+{ config, lib, pkgs, ... }:
+
+{
+  home.packages = with pkgs; [
+    vim
+    git
+    htop
+  ];
+
+  programs.git = {
+    enable = true;
+    userName = "My Name";
+    userEmail = "me@example.com";
+  };
+}
+```
+
+### With Dotfiles
+
+```nix
+{ inputs, ... }:
+
+{ config, lib, pkgs, ... }:
+
+{
+  home.packages = with pkgs; [ ripgrep fd bat ];
+
+  # Symlink dotfiles
+  home.file.".bashrc".source = ./dotfiles/bashrc;
+  home.file.".vimrc".source = ./dotfiles/vimrc;
+  
+  programs.git = {
+    enable = true;
+    userName = "My Name";
+    userEmail = "me@example.com";
+  };
+}
+```
+
+### With System Configuration (nixos.nix)
+
+```nix
+{ inputs, ... }:
+
+{ config, lib, pkgs, ... }:
+
+{
+  # Add user to docker group
+  users.users.myusername.extraGroups = [ "docker" ];
+  
+  # Install system package
+  environment.systemPackages = [ pkgs.docker ];
+}
+```
+
+## Integration Features
+
+External user modules:
+- Receive the same flake inputs as nixos-systems
+- Can use all home-manager options
+- Optionally provide system-level configuration (nixos.nix)
+- System zsh theme applied if `useZshTheme = true` (default)
+- System nvim config applied if `useNvimPlugins = true` (default)
+- Merged with inventory.nix user settings (groups, shell, etc.)
+
+## Development Workflow
+
+1. Create your user config repository with `home.nix`
+2. Test locally: `home = /path/to/local/repo;`
+3. Build: `nix build .#nixosConfigurations.hostname.config.system.build.toplevel`
+4. Commit and push changes
+5. Update users.nix with commit hash
+6. Deploy to systems
+
+## Benefits
+
+- **Personal Ownership**: Users maintain their own configs
+- **Version Control**: Track dotfile changes over time
+- **Portability**: Use same config across multiple machines
+- **Reproducibility**: Pin to specific commits
+- **Privacy**: Use private repositories for personal settings
+- **Separation**: Keep personal configs separate from system configs

templates/user/home.nix

@@ -0,0 +1,91 @@
+{ inputs, ... }:
+
+# ============================================================================
+# User Home Manager Configuration Template
+# ============================================================================
+# This file provides home-manager configuration for a user.
+# It will be imported into the NixOS system's home-manager configuration.
+#
+# Usage in users.nix:
+#   myusername = {
+#     description = "My Name";
+#     home = builtins.fetchGit {
+#       url = "https://github.com/username/dotfiles";
+#       rev = "commit-hash";
+#     };
+#   };
+#
+# This module receives the same `inputs` flake inputs as the main
+# nixos-systems configuration (nixpkgs, home-manager, etc.).
+
+{
+  config,
+  lib,
+  pkgs,
+  osConfig,  # Access to the OS-level config
+  ...
+}:
+
+{
+  # ========== Home Manager Configuration ==========
+  
+  # User identity (required)
+  home.username = lib.mkDefault config.home.username;  # Set by system
+  home.homeDirectory = lib.mkDefault config.home.homeDirectory;  # Set by system
+  home.stateVersion = lib.mkDefault "25.11";
+
+  # ========== Packages ==========
+  home.packages = with pkgs; [
+    # Add your preferred packages here
+    # htop
+    # ripgrep
+    # fd
+    # bat
+  ];
+
+  # ========== Programs ==========
+  
+  # Git configuration
+  programs.git = {
+    enable = true;
+    userName = "Your Name";
+    userEmail = "your.email@example.com";
+    extraConfig = {
+      init.defaultBranch = "main";
+    };
+  };
+
+  # Zsh configuration
+  programs.zsh = {
+    enable = true;
+    # System theme is applied automatically if useZshTheme = true in users.nix
+    # Add your custom zsh config here
+  };
+
+  # Neovim configuration
+  # programs.neovim = {
+  #   enable = true;
+  #   # System nvim config is applied automatically if useNvimPlugins = true
+  #   # Add your custom neovim config here
+  # };
+
+  # ========== Shell Environment ==========
+  
+  home.sessionVariables = {
+    EDITOR = "vim";
+    # Add your custom environment variables
+  };
+
+  # ========== Dotfiles ==========
+  
+  # You can manage dotfiles with home.file
+  # home.file.".bashrc".source = ./dotfiles/bashrc;
+  # home.file.".vimrc".source = ./dotfiles/vimrc;
+
+  # Or use programs.* options for better integration
+  
+  # ========== XDG Configuration ==========
+  
+  xdg.enable = true;
+  # xdg.configFile."app/config.conf".source = ./config/app.conf;
+}

templates/user/nixos.nix

@@ -0,0 +1,47 @@
+{ inputs, ... }:
+
+# ============================================================================
+# 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.
+#
+# 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
+#
+# This module receives the same `inputs` flake inputs as the main
+# nixos-systems configuration.
+
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+{
+  # ========== System Configuration ==========
+  
+  # Example: Enable a system service for this user
+  # systemd.services.my-user-service = {
+  #   description = "My User Service";
+  #   wantedBy = [ "multi-user.target" ];
+  #   serviceConfig = {
+  #     Type = "oneshot";
+  #     User = "myusername";
+  #     ExecStart = "${pkgs.bash}/bin/bash -c 'echo Hello'";
+  #   };
+  # };
+
+  # Example: Install system-wide packages needed by this user
+  # environment.systemPackages = with pkgs; [
+  #   docker
+  # ];
+
+  # Example: Add user to additional groups
+  # users.users.myusername.extraGroups = [ "docker" ];
+
+  # Most configuration should be in home.nix instead of here
+}