{
  description = "Nomarchy — the rock-solid reproducibility of NixOS, the polish of an opinionated desktop";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";

    home-manager = {
      url = "github:nix-community/home-manager/release-26.05";
      inputs.nixpkgs.follows = "nixpkgs";
    };

    stylix = {
      url = "github:danth/stylix";
      inputs.nixpkgs.follows = "nixpkgs";
      inputs.home-manager.follows = "home-manager";
    };
  };

  outputs = { self, nixpkgs, home-manager, stylix, ... }:
    let
      system = "x86_64-linux";
      username = "nomarchy"; # reference host only; downstream picks its own

      pkgs = import nixpkgs {
        inherit system;
        overlays = [ self.overlays.default ];
      };
    in
    {
      # ─── Downstream API ────────────────────────────────────────────
      # A user's machine flake imports these and layers its own
      # system.nix / home.nix on top (see templates/downstream).
      # Their theme-state.json lives in THEIR flake and is wired up via
      # the `nomarchy.stateFile` option — reading it stays pure.

      overlays.default = final: prev: {
        nomarchy-theme-sync = final.callPackage ./pkgs/nomarchy-theme-sync {
          # Presets baked into the package, so `nomarchy-theme-sync list`
          # works on machines that don't check out this repo.
          themesDir = ./themes;
        };
      };

      nixosModules.nomarchy = {
        imports = [ ./modules/nixos ];
        nixpkgs.overlays = [ self.overlays.default ];
      };

      homeModules.nomarchy = {
        # stylix's home module is injected here because it needs the
        # flake input; modules/home/stylix.nix only configures it.
        imports = [ stylix.homeModules.stylix ./modules/home ];
      };

      templates.default = {
        path = ./templates/downstream;
        description = "Nomarchy machine configuration (downstream flake)";
      };

      packages.${system} = {
        nomarchy-theme-sync = pkgs.nomarchy-theme-sync;
        default = pkgs.nomarchy-theme-sync;
      };

      # ─── Reference host ────────────────────────────────────────────
      # Deliberately split rebuild paths:
      #   system  → sudo nixos-rebuild switch --flake .#nomarchy   (rare)
      #   desktop → home-manager switch --flake .#nomarchy         (no sudo;
      #             this is what `nomarchy-theme-sync apply` runs)
      # Theme changes never touch the system layer, so they never need
      # root and never rebuild the world.
      nixosConfigurations.nomarchy = nixpkgs.lib.nixosSystem {
        inherit system;
        specialArgs = { inherit username; };
        modules = [
          self.nixosModules.nomarchy
          ./hosts/default/configuration.nix
        ];
      };

      homeConfigurations.${username} = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [
          self.homeModules.nomarchy
          {
            # The single source of truth — pure read: the file is part
            # of this flake's source.
            nomarchy.stateFile = ./theme-state.json;
            home = {
              inherit username;
              homeDirectory = "/home/${username}";
            };
          }
        ];
      };

      # ─── Live ISO ──────────────────────────────────────────────────
      # Full desktop on a bootable stick, no installation:
      #   nix build .#nixosConfigurations.nomarchy-live.config.system.build.isoImage
      # Test in QEMU with tools/test-live-iso.sh. See docs/TESTING.md.
      nixosConfigurations.nomarchy-live = nixpkgs.lib.nixosSystem {
        inherit system;
        specialArgs = { inherit username; nomarchySrc = self; };
        modules = [
          "${nixpkgs}/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix"
          self.nixosModules.nomarchy
          ./hosts/live.nix

          # The ISO is a sealed artifact, so the desktop is baked in via
          # the HM NixOS module (the installed-system split into
          # nixos-rebuild vs home-manager switch doesn't apply here —
          # though the seeded ~/.nomarchy flake still allows standalone
          # `home-manager switch` for theme testing).
          home-manager.nixosModules.home-manager
          {
            home-manager = {
              useGlobalPkgs = true;
              useUserPackages = true;
              users.${username} = {
                imports = [ self.homeModules.nomarchy ];
                nomarchy.stateFile = ./theme-state.json;
              };
            };

            # Keep the locked flake inputs in the ISO store so theme
            # switching on the live system works without a network: the
            # lockfile's narHashes resolve against these paths instead
            # of fetching from GitHub.
            system.extraDependencies = [
              nixpkgs.outPath
              home-manager.outPath
              stylix.outPath
            ];
          }
        ];
      };
    };
}