Commit 5ff7827d549c

@@ -67,50 +67,70 @@ nix flake metadata --json | jq .locks
 }
 ```
 
-### Complete Flake Template
+### Complete Flake Template (with flake-parts)
+
+**Always use flake-parts, NOT flake-utils.** flake-parts uses a modular `perSystem` pattern
+that is cleaner and more composable.
+
 ```nix
 {
   description = "Complete flake example";
 
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    flake-parts.url = "github:hercules-ci/flake-parts";
     home-manager = {
       url = "github:nix-community/home-manager";
       inputs.nixpkgs.follows = "nixpkgs";
     };
   };
 
-  outputs = { self, nixpkgs, home-manager }: let
-    system = "x86_64-linux";
-    pkgs = nixpkgs.legacyPackages.${system};
-  in {
-    # Packages
-    packages.${system} = {
-      default = pkgs.hello;
-      myapp = pkgs.callPackage ./pkgs/myapp { };
-    };
+  outputs = inputs@{ self, nixpkgs, flake-parts, home-manager }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
 
-    # NixOS configurations
-    nixosConfigurations = {
-      hostname = nixpkgs.lib.nixosSystem {
-        inherit system;
-        modules = [ ./configuration.nix ];
+      perSystem = { config, pkgs, system, ... }: {
+        # Packages (per-system)
+        packages = {
+          default = pkgs.hello;
+          myapp = pkgs.callPackage ./pkgs/myapp { };
+        };
+
+        # Checks (per-system)
+        checks = {
+          myapp = config.packages.myapp;
+        };
+
+        # Development shells (per-system)
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [ go gopls ];
+        };
+      };
+
+      # Non-per-system outputs
+      flake = {
+        # Overlays
+        overlays.default = final: prev: {
+          myapp = final.callPackage ./pkgs/myapp { };
+        };
+
+        # NixOS configurations
+        nixosConfigurations = {
+          hostname = nixpkgs.lib.nixosSystem {
+            system = "x86_64-linux";
+            modules = [ ./configuration.nix ];
+          };
+        };
+
+        # Home-manager configurations
+        homeConfigurations = {
+          "user@hostname" = home-manager.lib.homeManagerConfiguration {
+            pkgs = nixpkgs.legacyPackages.x86_64-linux;
+            modules = [ ./home.nix ];
+          };
+        };
       };
     };
-
-    # Home-manager configurations
-    homeConfigurations = {
-      "user@hostname" = home-manager.lib.homeManagerConfiguration {
-        inherit pkgs;
-        modules = [ ./home.nix ];
-      };
-    };
-
-    # Development shells
-    devShells.${system}.default = pkgs.mkShell {
-      buildInputs = with pkgs; [ go gopls ];
-    };
-  };
 }
 ```
 
@@ -161,7 +181,7 @@ inputs = {
     url = "github:owner/repo";
     inputs = {
       nixpkgs.follows = "nixpkgs";
-      flake-utils.follows = "flake-utils";
+      flake-parts.follows = "flake-parts";
     };
   };
 };
@@ -209,53 +229,34 @@ outputs = { self, nixpkgs }: {
 };
 ```
 
-### Per-System Outputs
-```nix
-{
-  outputs = { self, nixpkgs }: let
-    # Helper to generate for each system
-    forAllSystems = nixpkgs.lib.genAttrs [
-      "x86_64-linux"
-      "aarch64-linux"
-      "x86_64-darwin"
-      "aarch64-darwin"
-    ];
-  in {
-    packages = forAllSystems (system: {
-      default = nixpkgs.legacyPackages.${system}.hello;
-    });
+### Per-System Outputs (with flake-parts)
 
-    devShells = forAllSystems (system: let
-      pkgs = nixpkgs.legacyPackages.${system};
-    in {
-      default = pkgs.mkShell {
-        buildInputs = [ pkgs.go ];
-      };
-    });
-  };
-}
-```
+flake-parts handles per-system iteration automatically via `perSystem`:
 
-### Using flake-utils
 ```nix
 {
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-    flake-utils.url = "github:numtide/flake-utils";
+    flake-parts.url = "github:hercules-ci/flake-parts";
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system: let
-      pkgs = nixpkgs.legacyPackages.${system};
-    in {
-      packages.default = pkgs.hello;
-      devShells.default = pkgs.mkShell {
-        buildInputs = [ pkgs.go ];
+  outputs = inputs@{ self, nixpkgs, flake-parts }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+
+      perSystem = { config, pkgs, ... }: {
+        packages.default = pkgs.hello;
+        devShells.default = pkgs.mkShell {
+          buildInputs = [ pkgs.go ];
+        };
       };
-    });
+    };
 }
 ```
 
+> **Note:** Do NOT use `flake-utils`. Use `flake-parts` instead — it is more
+> modular, composable, and is the standard across all personal repositories.
+
 ## Managing Lock Files
 
 ### Lock File Structure
@@ -500,22 +501,18 @@ nix build git+https://example.com/repo.git
 7. **Use templates**: Standardize project structure
 8. **Version outputs**: Tag releases properly
 9. **Minimal inputs**: Only include what's needed
-10. **Use flake-utils**: Simplify multi-system outputs
+10. **Use flake-parts**: Simplify multi-system outputs (NOT flake-utils)
 
 ## Common Patterns
 
 ### Multi-System Support
+Use `flake-parts` — it handles multi-system automatically:
 ```nix
-{
-  outputs = { self, nixpkgs }: let
-    systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
-    forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f system);
-  in {
-    packages = forAllSystems (system: {
-      default = nixpkgs.legacyPackages.${system}.hello;
-    });
-  };
-}
+# systems list in mkFlake handles all the iteration
+systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+perSystem = { pkgs, ... }: {
+  packages.default = pkgs.hello;
+};
 ```
 
 ### Overlay Pattern

@@ -265,20 +265,32 @@ nix flake metadata
 ```
 
 ### Flake Structure
+
+**Use flake-parts, NOT flake-utils.** All personal flakes use `flake-parts` for multi-system support.
+
 ```nix
 {
   description = "Flake description";
 
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    flake-parts.url = "github:hercules-ci/flake-parts";
   };
 
-  outputs = { self, nixpkgs }: {
-    nixosConfigurations = { ... };
-    homeConfigurations = { ... };
-    packages = { ... };
-    devShells = { ... };
-  };
+  outputs = inputs@{ self, nixpkgs, flake-parts }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+
+      perSystem = { pkgs, ... }: {
+        packages.default = pkgs.hello;
+        devShells.default = pkgs.mkShell { buildInputs = [ pkgs.go ]; };
+      };
+
+      flake = {
+        nixosConfigurations = { ... };
+        overlays.default = final: prev: { ... };
+      };
+    };
 }
 ```