{
  description = "A flake to install k8s-homelab environment";

  # Add nixConfig to control what gets used in the flake
  nixConfig = {
    # Only allow these paths to be accessed by the builder
    allowed-uris = [
      "github:NixOS/nixpkgs"
      "github:numtide/devshell"
      "github:numtide/flake-utils"
    ];
    # Exclude everything but the flake.nix file from the build inputs
    flake-registry = "";
  };

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
    # TODO(quarto): remove this pin once nixpkgs ships a matched quarto+pandoc
    # pair again. nixpkgs quarto 1.9.x emits pandoc's renamed `syntax-highlighting`
    # option (was `highlight-style`), but no *released* pandoc accepts it yet, so
    # `quarto render` fails on current/unstable nixpkgs. nixos-25.05 predates the
    # quarto-1.9 bump (nixpkgs#480694) and provides a matched quarto+pandoc pair.
    # Ref: https://github.com/NixOS/nixpkgs/issues/519484
    nixpkgs-docs.url = "github:NixOS/nixpkgs/nixos-25.05";
    devshell.url = "github:numtide/devshell";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = {
    self,
    devshell,
    flake-utils,
    nixpkgs,
    nixpkgs-unstable,
    nixpkgs-docs
  }:
    flake-utils.lib.eachDefaultSystem (system: {
      devShells.default =
        let
          pkgs = import nixpkgs {
            inherit system;
            overlays = [
              devshell.overlays.default
              # When applied, the unstable nixpkgs set (declared in the flake inputs) will be accessible through 'pkgs.unstable'
              (final: prev: {
                unstable = import nixpkgs-unstable {
                  system = final.system;
                  config = { allowUnfree = true; };
                };
              })
              # (final: prev: {
              #   ansible = prev.python311.pkgs.ansible;
              #   ansible-lint = (prev.ansible-lint.override {
              #     python3 = prev.python311;
              #   });
              # })
            ];

            config = {
              allowUnfree = true;
            };
          };
          # TODO(quarto): drop this pinned docs toolchain once nixpkgs quarto and
          # pandoc are a compatible pair again (see nixpkgs-docs input above).
          docsPkgs = import nixpkgs-docs {
            inherit system;
            config = { allowUnfree = true; };
          };
          quartoPinned = docsPkgs.quarto;
          pandocPinned = docsPkgs.pandoc;
        in
        pkgs.devshell.mkShell {
          name = "k8s-devshell";
          # imports = [];
          # Force the pinned quarto to use its matched (pinned) pandoc, so it
          # never falls back to a newer profile/devshell pandoc.
          # Ref: https://github.com/NixOS/nixpkgs/issues/519484
          env = [
            {
              name = "QUARTO_PANDOC";
              value = "${pandocPinned}/bin/pandoc";
            }
          ];
          # a list of packages to add to the shell environment
          packages = with pkgs; [
            # ansible       # Radically simple IT automation
            # ansible-lint  # Best practices checker for Ansible
            _1password-cli # 1Password CLI tool
            # bws # Bitwarden Secrets Manager
            cloudflared # Client for various Cloudflare services
            # freelens # Kubernetes IDE
            fluxcd # flux CLI for gitops
            hadolint # Dockerfile Linter JavaScript API
            helmfile # Helmfile is a declarative spec for deploying helm charts
            # kopia          # Cross-platform backup tool
            krew # Package manager for kubectl plugins
            kubectl # Kubernetes CLI
            kubecolor # colorize kubectl output
            kubeconform # FAST Kubernetes manifests validator, with support for Custom Resources
            kubernetes-helm # helm CLI
            kustomize # Customization of kubernetes YAML configurations
            stern # Multi-pod/container log tailing for Kubernetes
            minijinja # CLI to render MiniJinja/Jinja2 templates
            minio-client # CLI for minio, An S3-compatible object storage server
            #--- docs (Great Docs / Quarto) ---
            # Pinned pre-1.9 pair via nixpkgs-docs; see TODO on the input above.
            quartoPinned # Scientific and technical publishing system (Great Docs renderer)
            pandocPinned # Document converter, matched to quartoPinned
            # nerdctl        # A Docker-compatible CLI for containerd
            openldap # Open source implementation of the Lightweight Directory Access Protocol
            restic # A backup program that is fast, efficient and secure
            # unstable.renovate # Cross-platform Dependency Automation # TODO: update renovate when it works; remove brew renovate
            # velero         # Kubernetes disaster recovery
            yq-go # Lightweight and portable command-line YAML processor
          ];
          # imports = [ (devshell.importTOML ./devshell.toml) ];
        };
    });
}