docs/nix-flakes: clarify extraSpecialArgs usage

Explain when to use extraSpecialArgs versus _module.args in the flake setup guides, and keep the generated standalone fixture aligned with the updated template output.

docs/manual/nix-flakes/nix-darwin.md

@@ -25,10 +25,8 @@ to that of NixOS. The `flake.nix` would be:
           {
             home-manager.useGlobalPkgs = true;
             home-manager.useUserPackages = true;
+            home-manager.extraSpecialArgs = { inherit inputs; };
             home-manager.users.jdoe = ./home.nix;
-
-            # Optionally, use home-manager.extraSpecialArgs to pass
-            # arguments to home.nix
           }
         ];
       };
@@ -37,6 +35,17 @@ to that of NixOS. The `flake.nix` would be:
 }
 ```
 
+Use `home-manager.extraSpecialArgs` to pass arguments from your flake to
+`home.nix` and any imported Home Manager modules. For example, the
+configuration above makes the complete `inputs` attrset available to modules,
+so they can declare arguments such as `{ inputs, ... }:`.
+
+The lower-level mechanism behind this is `_module.args`. Set
+`_module.args.<name>` from inside a module only when you need to provide a
+module argument from within the module graph itself. For values that originate
+outside the module graph, such as flake inputs, prefer
+`home-manager.extraSpecialArgs`.
+
 and it is also rebuilt with the nix-darwin generations. The rebuild
 command here may be `darwin-rebuild switch --flake <flake-uri>`.
 

docs/manual/nix-flakes/nixos.md

@@ -23,10 +23,8 @@ be as follows:
           {
             home-manager.useGlobalPkgs = true;
             home-manager.useUserPackages = true;
+            home-manager.extraSpecialArgs = { inherit inputs; };
             home-manager.users.jdoe = ./home.nix;
-
-            # Optionally, use home-manager.extraSpecialArgs to pass
-            # arguments to home.nix
           }
         ];
       };
@@ -35,6 +33,17 @@ be as follows:
 }
 ```
 
+Use `home-manager.extraSpecialArgs` to pass arguments from your flake to
+`home.nix` and any imported Home Manager modules. For example, the
+configuration above makes the complete `inputs` attrset available to modules,
+so they can declare arguments such as `{ inputs, ... }:`.
+
+The lower-level mechanism behind this is `_module.args`. Set
+`_module.args.<name>` from inside a module only when you need to provide a
+module argument from within the module graph itself. For values that originate
+outside the module graph, such as flake inputs, prefer
+`home-manager.extraSpecialArgs`.
+
 The Home Manager configuration is then part of the NixOS configuration
 and is automatically rebuilt with the system when using the appropriate
 command for the system, such as

docs/manual/nix-flakes/standalone.md

@@ -20,6 +20,36 @@ $ nix run home-manager/release-25.11 -- init --switch
 This will generate a `flake.nix` and a `home.nix` file in
 `~/.config/home-manager`, creating the directory if it does not exist.
 
+If you need to pass additional values from your flake to `home.nix` or any
+imported Home Manager modules, use `extraSpecialArgs` in the call to
+`home-manager.lib.homeManagerConfiguration`:
+
+``` nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    home-manager.url = "github:nix-community/home-manager";
+    home-manager.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = inputs@{ nixpkgs, home-manager, ... }: {
+    homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      extraSpecialArgs = { inherit inputs; };
+      modules = [ ./home.nix ];
+    };
+  };
+}
+```
+
+Any attribute in `extraSpecialArgs` becomes a module argument, so `home.nix`
+or imported modules can declare arguments such as `{ inputs, ... }:`.
+
+The lower-level mechanism behind this is `_module.args`. Set
+`_module.args.<name>` from inside a module only when you need to provide a
+module argument from within the module graph itself. For values that originate
+outside the module graph, such as flake inputs, prefer `extraSpecialArgs`.
+
 If you omit the `--switch` option then the activation will not happen.
 This is useful if you want to inspect and edit the configuration before
 activating it.

templates/nix-darwin/flake.nix

@@ -10,7 +10,7 @@
   };
 
   outputs =
-    {
+    inputs@{
       home-manager,
       darwin,
       ...
@@ -25,10 +25,8 @@
             {
               home-manager.useGlobalPkgs = true;
               home-manager.useUserPackages = true;
+              home-manager.extraSpecialArgs = { inherit inputs; };
               home-manager.users.jdoe = ./home.nix;
-
-              # Optionally, use home-manager.extraSpecialArgs to pass
-              # arguments to home.nix
             }
           ];
         };

templates/nixos/flake.nix

@@ -8,7 +8,7 @@
   };
 
   outputs =
-    { nixpkgs, home-manager, ... }:
+    inputs@{ nixpkgs, home-manager, ... }:
     {
       nixosConfigurations = {
         hostname = nixpkgs.lib.nixosSystem {
@@ -19,10 +19,8 @@
             {
               home-manager.useGlobalPkgs = true;
               home-manager.useUserPackages = true;
+              home-manager.extraSpecialArgs = { inherit inputs; };
               home-manager.users.jdoe = ./home.nix;
-
-              # Optionally, use home-manager.extraSpecialArgs to pass
-              # arguments to home.nix
             }
           ];
         };

templates/standalone/flake.nix

@@ -11,7 +11,7 @@
   };
 
   outputs =
-    { nixpkgs, home-manager, ... }:
+    inputs@{ nixpkgs, home-manager, ... }:
     let
       system = "x86_64-linux";
       pkgs = nixpkgs.legacyPackages.${system};
@@ -24,8 +24,7 @@
         # the path to your home.nix.
         modules = [ ./home.nix ];
 
-        # Optionally use extraSpecialArgs
-        # to pass through arguments to home.nix
+        extraSpecialArgs = { inherit inputs; };
       };
     };
 }

tests/integration/standalone/alice-flake-init.nix

@@ -11,7 +11,7 @@
   };
 
   outputs =
-    { nixpkgs, home-manager, ... }:
+    inputs@{ nixpkgs, home-manager, ... }:
     let
       system = "x86_64-linux";
       pkgs = nixpkgs.legacyPackages.${system};
@@ -24,8 +24,7 @@
         # the path to your home.nix.
         modules = [ ./home.nix ];
 
-        # Optionally use extraSpecialArgs
-        # to pass through arguments to home.nix
+        extraSpecialArgs = { inherit inputs; };
       };
     };
 }