{
  description = "Reusable NixOS + home-manager modules, with an example host";

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

    home-manager = {
      url = "github:nix-community/home-manager/release-26.05";
      inputs.nixpkgs.follows = "nixpkgs"; # Use our nixpkgs, not any pinned by home-manager.
    };

    # rust-overlay: precise, NixOS-patched Rust toolchains (any stable/nightly,
    # any component/target) exposed as pkgs.rust-bin. Used by the `rust` devShell
    # below. `follows` so it shares our nixpkgs. Bump with
    # `nix flake update rust-overlay`.
    rust-overlay = {
      url = "github:oxalica/rust-overlay";
      inputs.nixpkgs.follows = "nixpkgs";
    };

    # nixvim: declarative Neovim as home-manager options — the whole editor
    # (plugins, LSP, keymaps) lives in modules/nvim.nix, pinned by this flake's
    # lock. Track the release branch matching nixpkgs (a mismatched branch fails
    # with `vimPlugins.<name> not found`). `follows` keeps one nixpkgs: both are
    # on the same stable channel, so the version skew nixvim warns about (only an
    # issue against unstable) does not arise here.
    nixvim = {
      url = "github:nix-community/nixvim/nixos-26.05";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = inputs@{ self, nixpkgs, home-manager, rust-overlay, nixvim, ... }:
    let
      system = "x86_64-linux";
    in {
      # ---- Reusable modules ----------------------------------------------
      # Consume these from your own (private) inventory flake:
      #   imports = [ config.nixosModules.default ];
      #   home-manager.users.<you>.imports = [ config.homeModules.default ];
      nixosModules.default = import ./modules/nixos.nix;
      # nixvim's home-manager module rides along so `modules/nvim.nix` can set
      # `programs.nixvim.*`; consumers get the editor by importing this one module.
      homeModules.default = {
        imports = [ nixvim.homeModules.nixvim ./modules/home.nix ];
      };

      # ---- The example / template host -----------------------------------
      # Real and buildable; dogfoods the modules above. Clone, replace
      # hosts/example/hardware-configuration.nix, set hostName + user, rebuild.
      nixosConfigurations.example = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          self.nixosModules.default
          ./hosts/example
          home-manager.nixosModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.user.imports = [
              self.homeModules.default
              ./hosts/example/home.nix
            ];
          }
        ];
      };

      # ---- Template: `nix flake init -t github:<owner>/<repo>` -----------
      templates.default = {
        path = ./.;
        description = "NixOS + home-manager flake: module library + example host";
      };

      # ---- Rust dev shells -------------------------------------------------
      # DEFAULT for Rust work: one shared toolchain, used from any project
      # WITHOUT giving that project its own flake. In the project dir:
      #
      #   echo 'use flake <this-flake>#rust' > .envrc && direnv allow
      #
      # (or one-off, no direnv: `nix develop <this-flake>#rust`). Then
      # cargo/rustc/clippy/rustfmt/rust-analyzer appear on entry and vanish on
      # exit. direnv itself is enabled in modules/home.nix (programs.direnv). The
      # Rust version pin rides on THIS flake's flake.lock; bump it with
      # `nix flake update rust-overlay`.
      #
      # LIMITATION (the catch): a flake can only read files inside its own tree,
      # so this shell CANNOT read a project's local rust-toolchain.toml — the
      # `./` resolves to this flake, not the project dir. Every consumer
      # therefore gets this ONE toolchain. Want a few fixed alternates? Add more
      # named shells here (e.g. rust-nightly) and `use flake ...#name`.
      #
      # Give a project its OWN flake instead when it needs its own Rust version
      # driven by ITS OWN rust-toolchain.toml, OR native (C) deps (openssl,
      # pkg-config, protobuf, libclang...). That repo gets its own flake.nix +
      # committed flake.lock; there `rust-bin.fromRustupToolchainFile
      # ./rust-toolchain.toml` works (now `./` is that repo) and `buildInputs`
      # holds the C libs — per-repo and reproducible for anyone who clones it.
      devShells.${system} =
        let
          pkgs = import nixpkgs {
            inherit system;
            overlays = [ rust-overlay.overlays.default ];
          };
          rustToolchain = pkgs.rust-bin.stable.latest.default.override {
            extensions = [ "rust-src" "rust-analyzer" ];
          };
        in {
          rust = pkgs.mkShell {
            packages = [ rustToolchain ];
          };
        };
    };
}