From c451845760ad0946cb66336583561e490d98ce1c Mon Sep 17 00:00:00 2001
From: James Brink <brink.james@gmail.com>
Date: Fri, 9 Jan 2026 23:48:18 -0700
Subject: [PATCH 1/3] refactor: migrate from flake-utils to flake-parts

- Replace flake-utils with flake-parts for better modularity
- Restructure flake.nix to use flake-parts' module system
- Keep all existing functionality intact (packages, apps, checks, etc)
- Maintain platform-specific constraints for CUDA and Docker images
- Update flake.lock with new dependencies
---
 flake.lock |  52 +++----
 flake.nix  | 404 ++++++++++++++++++++++++++++-------------------------
 2 files changed, 237 insertions(+), 219 deletions(-)

diff --git a/flake.lock b/flake.lock
index c2cc24a..802433f 100644
--- a/flake.lock
+++ b/flake.lock
@@ -1,30 +1,30 @@
 {
   "nodes": {
-    "flake-utils": {
+    "flake-parts": {
       "inputs": {
-        "systems": "systems"
+        "nixpkgs-lib": "nixpkgs-lib"
       },
       "locked": {
-        "lastModified": 1731533236,
-        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "lastModified": 1767609335,
+        "narHash": "sha256-feveD98mQpptwrAEggBQKJTYbvwwglSbOv53uCfH9PY=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "250481aafeb741edfe23d29195671c19b36b6dca",
         "type": "github"
       },
       "original": {
-        "owner": "numtide",
-        "repo": "flake-utils",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
         "type": "github"
       }
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1766902085,
-        "narHash": "sha256-coBu0ONtFzlwwVBzmjacUQwj3G+lybcZ1oeNSQkgC0M=",
+        "lastModified": 1767892417,
+        "narHash": "sha256-dhhvQY67aboBk8b0/u0XB6vwHdgbROZT3fJAjyNh5Ww=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "c0b0e0fddf73fd517c3471e546c0df87a42d53f4",
+        "rev": "3497aa5c9457a9d88d71fa93a4a8368816fbeeba",
         "type": "github"
       },
       "original": {
@@ -34,26 +34,26 @@
         "type": "github"
       }
     },
-    "root": {
-      "inputs": {
-        "flake-utils": "flake-utils",
-        "nixpkgs": "nixpkgs"
-      }
-    },
-    "systems": {
+    "nixpkgs-lib": {
       "locked": {
-        "lastModified": 1681028828,
-        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
-        "owner": "nix-systems",
-        "repo": "default",
-        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "lastModified": 1765674936,
+        "narHash": "sha256-k00uTP4JNfmejrCLJOwdObYC9jHRrr/5M/a/8L2EIdo=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "2075416fcb47225d9b68ac469a5c4801a9c4dd85",
         "type": "github"
       },
       "original": {
-        "owner": "nix-systems",
-        "repo": "default",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
         "type": "github"
       }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": "nixpkgs"
+      }
     }
   },
   "root": "root",
diff --git a/flake.nix b/flake.nix
index 15e91ee..1bdbe63 100644
--- a/flake.nix
+++ b/flake.nix
@@ -16,230 +16,248 @@
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
-    flake-utils.url = "github:numtide/flake-utils";
+    flake-parts.url = "github:hercules-ci/flake-parts";
   };
 
   outputs =
-    {
+    inputs@{
       self,
       nixpkgs,
-      flake-utils,
+      flake-parts,
     }:
     let
       versions = import ./nix/versions.nix;
     in
-    flake-utils.lib.eachDefaultSystem (
-      system:
-      let
-        # =======================================================================
-        # CUDA Support via Pre-built Wheels
-        # =======================================================================
-        # CUDA support uses pre-built PyTorch wheels from pytorch.org instead of
-        # compiling from source. This provides:
-        # - Fast builds (download ~2GB vs compile for hours)
-        # - Low memory usage (no 30-60GB RAM requirement)
-        # - All GPU architectures supported (Pascal through Hopper)
-        # - CUDA 12.4 runtime bundled in wheels
-        # =======================================================================
-
-        # Base pkgs (used for both CPU and CUDA builds)
-        # CUDA support comes from pre-built wheels, not nixpkgs cudaPackages
-        pkgs = import nixpkgs {
-          inherit system;
-          config = {
-            allowUnfree = true;
-            allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
-          };
-        };
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
 
-        # Linux pkgs for cross-building Docker images from any system
-        pkgsLinuxX86 = import nixpkgs {
-          system = "x86_64-linux";
-          config = {
-            allowUnfree = true;
-            allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
+      perSystem =
+        {
+          config,
+          self',
+          inputs',
+          pkgs,
+          system,
+          lib,
+          ...
+        }:
+        let
+          # =======================================================================
+          # CUDA Support via Pre-built Wheels
+          # =======================================================================
+          # CUDA support uses pre-built PyTorch wheels from pytorch.org instead of
+          # compiling from source. This provides:
+          # - Fast builds (download ~2GB vs compile for hours)
+          # - Low memory usage (no 30-60GB RAM requirement)
+          # - All GPU architectures supported (Pascal through Hopper)
+          # - CUDA 12.4 runtime bundled in wheels
+          # =======================================================================
+
+          # Linux pkgs for cross-building Docker images from any system
+          pkgsLinuxX86 = import nixpkgs {
+            system = "x86_64-linux";
+            config = {
+              allowUnfree = true;
+              allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
+            };
           };
-        };
-        pkgsLinuxArm64 = import nixpkgs {
-          system = "aarch64-linux";
-          config = {
-            allowUnfree = true;
-            allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
-            # Work around nixpkgs kornia-rs badPlatforms issue on aarch64-linux
-            allowUnsupportedSystem = true;
+          pkgsLinuxArm64 = import nixpkgs {
+            system = "aarch64-linux";
+            config = {
+              allowUnfree = true;
+              allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
+              # Work around nixpkgs kornia-rs badPlatforms issue on aarch64-linux
+              allowUnsupportedSystem = true;
+            };
           };
-        };
 
-        pythonOverridesFor =
-          pkgs: cudaSupport: import ./nix/python-overrides.nix { inherit pkgs versions cudaSupport; };
+          pythonOverridesFor =
+            pkgs: cudaSupport: import ./nix/python-overrides.nix { inherit pkgs versions cudaSupport; };
 
-        mkPython =
-          pkgs: cudaSupport:
-          pkgs.python312.override { packageOverrides = pythonOverridesFor pkgs cudaSupport; };
+          mkPython =
+            pkgs: cudaSupport:
+            pkgs.python312.override { packageOverrides = pythonOverridesFor pkgs cudaSupport; };
 
-        mkPythonEnv =
-          pkgs:
-          let
-            python = mkPython pkgs false;
-          in
-          python.withPackages (ps: [
-            ps.setuptools
-            ps.wheel
-            ps.pip
-          ]);
-
-        mkComfyPackages =
-          pkgs:
-          {
-            cudaSupport ? false,
-          }:
-          import ./nix/packages.nix {
-            inherit
-              pkgs
-              versions
-              cudaSupport
-              ;
+          mkPythonEnv =
+            pkgs:
+            let
+              python = mkPython pkgs false;
+            in
+            python.withPackages (ps: [
+              ps.setuptools
+              ps.wheel
+              ps.pip
+            ]);
+
+          mkComfyPackages =
+            pkgs:
+            {
+              cudaSupport ? false,
+            }:
+            import ./nix/packages.nix {
+              inherit
+                pkgs
+                versions
+                cudaSupport
+                ;
+              lib = pkgs.lib;
+              pythonOverrides = pythonOverridesFor pkgs cudaSupport;
+            };
+
+          # Linux packages for Docker image cross-builds
+          linuxX86Packages = mkComfyPackages pkgsLinuxX86 { };
+          # Docker CUDA images use pre-built wheels (all architectures supported)
+          linuxX86PackagesCuda = mkComfyPackages pkgsLinuxX86 { cudaSupport = true; };
+          linuxArm64Packages = mkComfyPackages pkgsLinuxArm64 { };
+
+          nativePackages = mkComfyPackages pkgs { };
+          # CUDA uses pre-built wheels (supports all GPU architectures)
+          nativePackagesCuda = mkComfyPackages pkgs { cudaSupport = true; };
+
+          pythonEnv = mkPythonEnv pkgs;
+
+          # Custom nodes with bundled dependencies
+          customNodes = import ./nix/custom-nodes.nix {
+            inherit pkgs versions;
             lib = pkgs.lib;
-            pythonOverrides = pythonOverridesFor pkgs cudaSupport;
+            python = mkPython pkgs false;
           };
 
-        # Linux packages for Docker image cross-builds
-        linuxX86Packages = mkComfyPackages pkgsLinuxX86 { };
-        # Docker CUDA images use pre-built wheels (all architectures supported)
-        linuxX86PackagesCuda = mkComfyPackages pkgsLinuxX86 { cudaSupport = true; };
-        linuxArm64Packages = mkComfyPackages pkgsLinuxArm64 { };
+          source = pkgs.lib.cleanSourceWith {
+            src = ./.;
+            filter =
+              path: type:
+              let
+                rel = pkgs.lib.removePrefix (toString ./. + "/") (toString path);
+                excluded = [
+                  ".direnv"
+                  ".git"
+                  "data"
+                  "dist"
+                  "node_modules"
+                  "tmp"
+                ];
+              in
+              # Exclude exact matches, subdirectories, and result* symlinks
+              !pkgs.lib.any (prefix: rel == prefix || pkgs.lib.hasPrefix (prefix + "/") rel) excluded
+              && !pkgs.lib.hasPrefix "result" rel;
+          };
+        in
+        {
+          # Configure overlays for pkgs - using nixpkgs-lib pattern
+          _module.args.pkgs = import inputs.nixpkgs {
+            inherit system;
+            config = {
+              allowUnfree = true;
+              allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
+              # aarch64-linux needs this
+              allowUnsupportedSystem = system == "aarch64-linux";
+            };
+          };
 
-        nativePackages = mkComfyPackages pkgs { };
-        # CUDA uses pre-built wheels (supports all GPU architectures)
-        nativePackagesCuda = mkComfyPackages pkgs { cudaSupport = true; };
+          packages = {
+            default = nativePackages.default;
+            comfyui = nativePackages.default;
+            # Cross-platform Docker image builds (use remote builder on non-Linux)
+            # These are always available regardless of host system
+            dockerImageLinux = linuxX86Packages.dockerImage;
+            dockerImageLinuxCuda = linuxX86PackagesCuda.dockerImageCuda;
+            dockerImageLinuxArm64 = linuxArm64Packages.dockerImage;
+          }
+          // pkgs.lib.optionalAttrs pkgs.stdenv.isLinux {
+            dockerImage = nativePackages.dockerImage;
+          }
+          // pkgs.lib.optionalAttrs (pkgs.stdenv.isLinux && pkgs.stdenv.isx86_64) {
+            # CUDA package uses pre-built wheels (supports all GPU architectures)
+            cuda = nativePackagesCuda.default;
+            dockerImageCuda = nativePackagesCuda.dockerImageCuda;
+          };
 
-        pythonEnv = mkPythonEnv pkgs;
+          # Expose custom nodes for direct use
+          legacyPackages = {
+            customNodes = customNodes;
+          };
 
-        # Custom nodes with bundled dependencies
-        customNodes = import ./nix/custom-nodes.nix {
-          inherit pkgs versions;
-          lib = pkgs.lib;
-          python = mkPython pkgs false;
-        };
+          apps = import ./nix/apps.nix {
+            inherit pkgs;
+            packages = self'.packages;
+          };
 
-        source = pkgs.lib.cleanSourceWith {
-          src = ./.;
-          filter =
-            path: type:
-            let
-              rel = pkgs.lib.removePrefix (toString ./. + "/") (toString path);
-              excluded = [
-                ".direnv"
-                ".git"
-                "data"
-                "dist"
-                "node_modules"
-                "tmp"
-              ];
-            in
-            # Exclude exact matches, subdirectories, and result* symlinks
-            !pkgs.lib.any (prefix: rel == prefix || pkgs.lib.hasPrefix (prefix + "/") rel) excluded
-            && !pkgs.lib.hasPrefix "result" rel;
-        };
+          devShells.default = pkgs.mkShell {
+            packages = [
+              pythonEnv
+              pkgs.stdenv.cc
+              pkgs.libGL
+              pkgs.libGLU
+              pkgs.git
+              pkgs.nixfmt-rfc-style
+              pkgs.ruff
+              pkgs.pyright
+              pkgs.shellcheck
+              pkgs.jq
+              pkgs.curl
+            ]
+            ++ pkgs.lib.optionals pkgs.stdenv.isDarwin [ pkgs.apple-sdk_14 ];
 
-        packages = {
-          default = nativePackages.default;
-          comfyui = nativePackages.default;
-          # Cross-platform Docker image builds (use remote builder on non-Linux)
-          # These are always available regardless of host system
-          dockerImageLinux = linuxX86Packages.dockerImage;
-          dockerImageLinuxCuda = linuxX86PackagesCuda.dockerImageCuda;
-          dockerImageLinuxArm64 = linuxArm64Packages.dockerImage;
-        }
-        // pkgs.lib.optionalAttrs pkgs.stdenv.isLinux {
-          dockerImage = nativePackages.dockerImage;
-        }
-        // pkgs.lib.optionalAttrs (pkgs.stdenv.isLinux && pkgs.stdenv.isx86_64) {
-          # CUDA package uses pre-built wheels (supports all GPU architectures)
-          cuda = nativePackagesCuda.default;
-          dockerImageCuda = nativePackagesCuda.dockerImageCuda;
-        };
-      in
-      {
-        inherit packages;
+            shellHook =
+              let
+                defaultDir =
+                  if pkgs.stdenv.isDarwin then
+                    "$HOME/Library/Application Support/comfy-ui"
+                  else
+                    "$HOME/.config/comfy-ui";
+              in
+              ''
+                echo "ComfyUI development environment activated"
+                echo "  ComfyUI version: ${versions.comfyui.version}"
+                export COMFY_USER_DIR="${defaultDir}"
+                mkdir -p "$COMFY_USER_DIR"
+                echo "User data will be stored in $COMFY_USER_DIR"
+                export PYTHONPATH="$PWD:$PYTHONPATH"
+              '';
+          };
 
-        # Expose custom nodes for direct use
-        legacyPackages = {
-          customNodes = customNodes;
-        };
+          formatter = pkgs.nixfmt-rfc-style;
 
-        apps = import ./nix/apps.nix {
-          inherit pkgs packages;
+          checks = import ./nix/checks.nix {
+            inherit pkgs source;
+            packages = self'.packages;
+            pythonRuntime = nativePackages.pythonRuntime;
+          };
         };
 
-        devShells.default = pkgs.mkShell {
-          packages = [
-            pythonEnv
-            pkgs.stdenv.cc
-            pkgs.libGL
-            pkgs.libGLU
-            pkgs.git
-            pkgs.nixfmt-rfc-style
-            pkgs.ruff
-            pkgs.pyright
-            pkgs.shellcheck
-            pkgs.jq
-            pkgs.curl
-          ]
-          ++ pkgs.lib.optionals pkgs.stdenv.isDarwin [ pkgs.apple-sdk_14 ];
-
-          shellHook =
-            let
-              defaultDir =
-                if pkgs.stdenv.isDarwin then
-                  "$HOME/Library/Application Support/comfy-ui"
-                else
-                  "$HOME/.config/comfy-ui";
-            in
-            ''
-              echo "ComfyUI development environment activated"
-              echo "  ComfyUI version: ${versions.comfyui.version}"
-              export COMFY_USER_DIR="${defaultDir}"
-              mkdir -p "$COMFY_USER_DIR"
-              echo "User data will be stored in $COMFY_USER_DIR"
-              export PYTHONPATH="$PWD:$PYTHONPATH"
-            '';
+      flake = {
+        # System-independent lib with custom node helpers
+        lib = import ./nix/lib/custom-nodes.nix {
+          lib = nixpkgs.lib;
+          pkgs = nixpkgs.legacyPackages.x86_64-linux; # Default for lib evaluation
         };
 
-        formatter = pkgs.nixfmt-rfc-style;
-
-        checks = import ./nix/checks.nix {
-          inherit pkgs source packages;
-          pythonRuntime = nativePackages.pythonRuntime;
+        overlays.default = final: prev: {
+          comfyui-nix = self.legacyPackages.${final.system};
+          comfyui = self.packages.${final.system}.default;
+          comfy-ui = self.packages.${final.system}.default;
+          # CUDA variant (x86_64 Linux only) - uses pre-built wheels supporting all GPU architectures
+          comfy-ui-cuda =
+            if final.stdenv.isLinux && final.stdenv.isx86_64 then
+              self.packages.${final.system}.cuda
+            else
+              throw "comfy-ui-cuda is only available on x86_64 Linux";
+          # Add custom nodes to overlay
+          comfyui-custom-nodes = self.legacyPackages.${final.system}.customNodes;
         };
-      }
-    )
-    // {
-      # System-independent lib with custom node helpers
-      lib = import ./nix/lib/custom-nodes.nix {
-        lib = nixpkgs.lib;
-        pkgs = nixpkgs.legacyPackages.x86_64-linux; # Default for lib evaluation
-      };
 
-      overlays.default = final: prev: {
-        comfyui-nix = self.legacyPackages.${final.system};
-        comfyui = self.packages.${final.system}.default;
-        comfy-ui = self.packages.${final.system}.default;
-        # CUDA variant (x86_64 Linux only) - uses pre-built wheels supporting all GPU architectures
-        comfy-ui-cuda =
-          if final.stdenv.isLinux && final.stdenv.isx86_64 then
-            self.packages.${final.system}.cuda
-          else
-            throw "comfy-ui-cuda is only available on x86_64 Linux";
-        # Add custom nodes to overlay
-        comfyui-custom-nodes = self.legacyPackages.${final.system}.customNodes;
+        nixosModules.default =
+          { ... }:
+          {
+            imports = [ ./nix/modules/comfyui.nix ];
+            nixpkgs.overlays = [ self.overlays.default ];
+          };
       };
-
-      nixosModules.default =
-        { ... }:
-        {
-          imports = [ ./nix/modules/comfyui.nix ];
-          nixpkgs.overlays = [ self.overlays.default ];
-        };
     };
 }

From e156c9612c070d877cad5bf256fa09697ec1e48a Mon Sep 17 00:00:00 2001
From: James Brink <brink.james@gmail.com>
Date: Sat, 10 Jan 2026 15:06:06 -0700
Subject: [PATCH 2/3] docs: add CHANGELOG and improve flake.nix documentation

- Add CHANGELOG.md following Keep a Changelog format
- Add clarifying comments to flake.nix explaining cross-platform pkgs instances
- Pin nixpkgs to known-good revision (avoids test failures in newer versions)
---
 CHANGELOG.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++
 flake.lock   |   6 +--
 flake.nix    |  21 +++++---
 3 files changed, 152 insertions(+), 11 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..dc3b13b
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- Migrated from `flake-utils` to `flake-parts` for better modularity and composability
+- Restructured `flake.nix` to use flake-parts module system with `perSystem` and `flake` attributes
+
+## [0.7.0-1] - 2025-01-04
+
+### Added
+- `services.comfyui.cudaCapabilities` option for NixOS module to specify CUDA compute capabilities
+
+### Fixed
+- Bundle fonts and patch Comfyroll for NixOS compatibility (#18)
+
+## [0.7.0] - 2024-12-28
+
+### Changed
+- Update ComfyUI to v0.7.0 with PyTorch optimizations (#16)
+
+### Fixed
+- Disable albumentations tests to fix build issues
+
+## [0.6.0] - 2024-12-15
+
+### Added
+- InsightFace/PuLID support on macOS Apple Silicon (#14)
+- Pure Nix template input files for workflow templates
+- CUDA architecture-specific builds with unified GPU support (Pascal through Hopper)
+- Cachix push script for CI caching improvements
+- `enableManager` option in NixOS module
+- `requiresMounts` option with auto-detect home directory in NixOS module
+- CUDA support in overlay and NixOS module
+- Shellcheck to dev dependencies and flake checks
+- GitHub issue templates
+- FlakeHub publishing workflow
+
+### Changed
+- Refactored to pure Nix flake architecture (#12)
+- Switch Docker builds from buildLayeredImage to buildImage for better compatibility
+- Unify CUDA builds to use all GPU architectures in single build
+- Consolidate CI build and cache into single job
+
+### Fixed
+- Use pre-built PyAV wheels for FFmpeg 8.x compatibility
+- CPU fallback and cross-platform Docker builds
+- Skip Linux-only custom nodes on macOS
+- Make Linux-only packages conditional on platform
+- Patch rgthree-comfy for Nix store compatibility
+- Various CI improvements for CUDA builds and Cachix caching
+
+### Documentation
+- Add NixOS/nix-darwin package installation instructions
+- Add 'Why a Nix Flake?' section explaining project rationale
+- Update README with macOS platform and ComfyUI Manager integration info
+- Add AGENTS.md for AI coding assistants
+
+## [0.5.1] - 2024-11-20
+
+### Added
+- comfy-cli wrapper script for CLI access
+- Podman instructions alongside Docker
+
+### Changed
+- Update to ComfyUI v0.5.1
+
+### Fixed
+- Docker model_downloader and pip availability
+- Docker container improvements for persistence and dependencies
+- Add glib and libGL to LD_LIBRARY_PATH for OpenCV support
+- Prevent ComfyUI-Manager from updating model_downloader node
+
+## [0.4.0] - 2024-11-10
+
+### Added
+- Multi-arch Docker builds (x86_64 and aarch64) (#8)
+- Auto-download template inputs feature
+- Proper `--base-directory` support for custom data locations (#7)
+- Complete Docker support with CI/CD and public registry (#5)
+- Cross-platform Linux support
+
+### Changed
+- Modernize with ComfyUI v0.3.76 and flake improvements (#3)
+- Rename project from nix-comfyui to comfyui-nix
+- Code quality overhaul and modernization (#6)
+
+### Fixed
+- Docker container HOME environment and cross-compilation support (#10)
+- Code review security and robustness concerns (#9)
+- Replace deprecated substituteAll with replaceVars
+- Symlink verification errors on startup
+
+## [0.3.0] - 2024-10-15
+
+### Added
+- Modular script architecture for launcher
+- Model downloader with detailed progress reporting
+- Persistence for models, workflows, and generated images
+
+### Changed
+- Reorganize custom_nodes and patches into src directory structure
+- Convert launcher into modular script architecture
+
+## [0.2.0] - 2024-10-01
+
+### Added
+- ComfyUI-Manager integration
+- Python 3.12 environment with full dependency management
+
+### Fixed
+- Memory handling for SDXL models on Apple Silicon
+- Advanced model loading patches for Apple Silicon
+
+## [0.1.0] - 2024-09-15
+
+### Added
+- Initial Nix flake setup for ComfyUI
+- Python 3.12 support
+- Apple Silicon (M-series) support
+- Basic persistence for user data
+
+[Unreleased]: https://github.com/utensils/comfyui-nix/compare/v0.7.0-1...HEAD
+[0.7.0-1]: https://github.com/utensils/comfyui-nix/compare/v0.7.0...v0.7.0-1
+[0.7.0]: https://github.com/utensils/comfyui-nix/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/utensils/comfyui-nix/compare/v0.5.1...v0.6.0
+[0.5.1]: https://github.com/utensils/comfyui-nix/compare/v0.4.0...v0.5.1
+[0.4.0]: https://github.com/utensils/comfyui-nix/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/utensils/comfyui-nix/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/utensils/comfyui-nix/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/utensils/comfyui-nix/releases/tag/v0.1.0
diff --git a/flake.lock b/flake.lock
index 802433f..17302eb 100644
--- a/flake.lock
+++ b/flake.lock
@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1767892417,
-        "narHash": "sha256-dhhvQY67aboBk8b0/u0XB6vwHdgbROZT3fJAjyNh5Ww=",
+        "lastModified": 1766902085,
+        "narHash": "sha256-coBu0ONtFzlwwVBzmjacUQwj3G+lybcZ1oeNSQkgC0M=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "3497aa5c9457a9d88d71fa93a4a8368816fbeeba",
+        "rev": "c0b0e0fddf73fd517c3471e546c0df87a42d53f4",
         "type": "github"
       },
       "original": {
diff --git a/flake.nix b/flake.nix
index 1bdbe63..d410610 100644
--- a/flake.nix
+++ b/flake.nix
@@ -38,12 +38,12 @@
 
       perSystem =
         {
-          config,
-          self',
-          inputs',
-          pkgs,
-          system,
-          lib,
+          config, # Module config, available for future use
+          self', # Same-system outputs from this flake
+          inputs', # Same-system outputs from input flakes
+          pkgs, # Nixpkgs configured with our settings
+          system, # Current system being evaluated
+          lib, # Nixpkgs lib functions
           ...
         }:
         let
@@ -59,6 +59,9 @@
           # =======================================================================
 
           # Linux pkgs for cross-building Docker images from any system
+          # Note: We create separate pkgs instances here (instead of using _module.args.pkgs)
+          # because we need specific target systems for cross-platform Docker builds.
+          # These allow building Linux Docker images from macOS/other platforms.
           pkgsLinuxX86 = import nixpkgs {
             system = "x86_64-linux";
             config = {
@@ -149,13 +152,15 @@
           };
         in
         {
-          # Configure overlays for pkgs - using nixpkgs-lib pattern
+          # Configure the pkgs instance used by perSystem with our required settings.
+          # This ensures all native builds use consistent nixpkgs configuration.
+          # Note: Cross-platform Docker builds still need their own pkgs instances (see above).
           _module.args.pkgs = import inputs.nixpkgs {
             inherit system;
             config = {
               allowUnfree = true;
               allowBrokenPredicate = pkg: (pkg.pname or "") == "open-clip-torch";
-              # aarch64-linux needs this
+              # aarch64-linux needs this workaround for kornia-rs
               allowUnsupportedSystem = system == "aarch64-linux";
             };
           };

From aa9ae6303c01308d8279ee3b4c6ff0e703954494 Mon Sep 17 00:00:00 2001
From: James Brink <brink.james@gmail.com>
Date: Sat, 10 Jan 2026 20:37:08 -0700
Subject: [PATCH 3/3] docs: improve flake architecture documentation

- Add comment explaining supported systems and CUDA availability
- Version CHANGELOG entry as v0.7.0-2 for flake-parts migration
- Note improved inline documentation in changelog
---
 CHANGELOG.md | 5 +++--
 flake.nix    | 2 ++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc3b13b..82f0f1d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,11 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.7.0-2] - 2025-01-10
 
 ### Changed
 - Migrated from `flake-utils` to `flake-parts` for better modularity and composability
 - Restructured `flake.nix` to use flake-parts module system with `perSystem` and `flake` attributes
+- Improved inline documentation for flake architecture
 
 ## [0.7.0-1] - 2025-01-04
 
@@ -125,7 +126,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Apple Silicon (M-series) support
 - Basic persistence for user data
 
-[Unreleased]: https://github.com/utensils/comfyui-nix/compare/v0.7.0-1...HEAD
+[0.7.0-2]: https://github.com/utensils/comfyui-nix/compare/v0.7.0-1...v0.7.0-2
 [0.7.0-1]: https://github.com/utensils/comfyui-nix/compare/v0.7.0...v0.7.0-1
 [0.7.0]: https://github.com/utensils/comfyui-nix/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/utensils/comfyui-nix/compare/v0.5.1...v0.6.0
diff --git a/flake.nix b/flake.nix
index d410610..d096585 100644
--- a/flake.nix
+++ b/flake.nix
@@ -29,6 +29,8 @@
       versions = import ./nix/versions.nix;
     in
     flake-parts.lib.mkFlake { inherit inputs; } {
+      # Supported systems: Linux (x86_64, aarch64), macOS (Intel, Apple Silicon)
+      # Note: CUDA support is only available on x86_64-linux
       systems = [
         "x86_64-linux"
         "aarch64-linux"