From 341d8ecf4527efba457daa8c0620185c9fcf3eb4 Mon Sep 17 00:00:00 2001
From: jasmine <its.jassy@pm.me>
Date: Sun, 5 Oct 2025 16:40:48 +0800
Subject: [PATCH] docs: add explanatory comments to global configurations

Add comprehensive inline documentation to both NixOS and Home Manager
global configuration files, explaining the purpose of each section,
overlay usage, unfree package policy, and configuration settings.
---
 home-manager/sajenim/global/default.nix | 29 +++++++++++++++++--------
 nixos/common/global/default.nix         | 25 +++++++++++++++------
 2 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/home-manager/sajenim/global/default.nix b/home-manager/sajenim/global/default.nix
index 6d376e5..d938728 100644
--- a/home-manager/sajenim/global/default.nix
+++ b/home-manager/sajenim/global/default.nix
@@ -1,42 +1,53 @@
+# Global Home Manager configuration for user sajenim.
+# This module provides base user settings, nixpkgs configuration, and core imports
+# that are inherited across all hosts where this user is configured.
 {outputs, lib, ...}: {
   imports = [
-    ./zsh.nix
+    ./zsh.nix # Shell configuration and plugins
   ];
 
+  # Nixpkgs configuration - applies overlays and sets package acceptance policy
   nixpkgs = {
+    # Apply custom overlays to extend/modify the package set
     overlays = [
-      outputs.overlays.additions
-      outputs.overlays.modifications
-      outputs.overlays.unstable-packages
+      outputs.overlays.additions      # Custom packages from pkgs/
+      outputs.overlays.modifications  # Package patches and modifications
+      outputs.overlays.unstable-packages # Unstable channel packages
     ];
+
     config = {
+      # Default to free software only - unfree packages must be explicitly allowed
       allowUnfree = false;
-      # Centralized unfree package allowlist.
+
+      # Centralized unfree package allowlist for Home Manager user configuration.
       # Note: nixpkgs.config.allowUnfreePredicate doesn't merge across modules - only the
       # last definition wins. To maintain explicit control over unfree packages, we list
       # all allowed packages here rather than scattering predicates across feature modules.
       allowUnfreePredicate = pkg:
         builtins.elem (lib.getName pkg) [
-          # Editors
+          # Development tools
           "claude-code"
           "idea-ultimate"
           "idea-ultimate-with-plugins"
-          # Desktop
-          "discord"
         ];
     };
   };
 
+  # Enable Home Manager to manage itself
   programs.home-manager.enable = true;
 
+  # User identity and base configuration
   home = {
     username = "sajenim";
     homeDirectory = "/home/sajenim";
     sessionVariables = {
-      EDITOR = "nvim";
+      EDITOR = "nvim"; # Default text editor for CLI operations
     };
   };
 
+  # Automatically restart systemd user services on configuration changes
   systemd.user.startServices = "sd-switch";
+
+  # Home Manager state version - don't change this after initial setup
   home.stateVersion = "22.11";
 }
diff --git a/nixos/common/global/default.nix b/nixos/common/global/default.nix
index f49fb35..4e72382 100644
--- a/nixos/common/global/default.nix
+++ b/nixos/common/global/default.nix
@@ -1,20 +1,28 @@
+# Global NixOS configuration shared across all hosts.
+# This module provides base system settings, nixpkgs configuration, and core imports
+# that every host in this configuration inherits.
 {outputs, lib, ...}: {
   imports = [
-    ./age.nix
-    ./env.nix
-    ./nix.nix
-    ./ssh.nix
+    ./age.nix # Secret management with agenix
+    ./env.nix # Environment variables and shell configuration
+    ./nix.nix # Nix daemon settings, features, and garbage collection
+    ./ssh.nix # SSH server configuration and authorized keys
   ];
 
+  # Nixpkgs configuration - applies overlays and sets package acceptance policy
   nixpkgs = {
+    # Apply custom overlays to extend/modify the package set
     overlays = [
       # Overlays our own flake exports
-      outputs.overlays.additions
-      outputs.overlays.modifications
-      outputs.overlays.unstable-packages
+      outputs.overlays.additions      # Custom packages from pkgs/
+      outputs.overlays.modifications  # Package patches and modifications
+      outputs.overlays.unstable-packages # Unstable channel packages
     ];
+
     config = {
+      # Default to free software only - unfree packages must be explicitly allowed
       allowUnfree = false;
+
       # Centralized unfree package allowlist for NixOS system configuration.
       # Note: nixpkgs.config.allowUnfreePredicate doesn't merge across modules - only the
       # last definition wins. To maintain explicit control over unfree packages, we list
@@ -30,10 +38,13 @@
     };
   };
 
+  # Localization settings - Australian English locale and Perth timezone
   i18n.defaultLocale = "en_AU.UTF-8";
   time.timeZone = "Australia/Perth";
 
+  # Network configuration - default domain for host FQDNs
   networking.domain = "kanto.dev";
 
+  # Enable non-free firmware for hardware compatibility (WiFi, GPU drivers, etc.)
   hardware.enableRedistributableFirmware = true;
 }