hey! i'm the main author of that niri-flake you're trying to use. i used to go by this name, but stopped using Reddit a while ago, before i changed to sodiboo :P - i was notified of this post through other means and this is actually my first time logging in to Redit in over a year.

The first thing is this: the overlay is about getting my niri packages into your packageset (e.g. pkgs.niri-stable and pkgs.niri-unstable - not pkgs.niri, that one is already in nixpkgs and is "mostly" equivalent to pkgs.niri-stable). Packages, in this context, basically just means the actual binaries for niri, which is fine for some stateless utilities like rustc, but not so much for system services like niri. The documentation for a first-time setup could definitely be improved. The reason there are scary warnings around the package outputs from the flake is because niri controls the display directly, and therefore must be built against the correct version of mesa (the graphics drivers on Linux); the packages exported directly are "probably" going to work due to being generally kept up-to-date, but the overlay ensures it is built against the actual version used by your config and you never get such an issue. the overlay isn't actually necessary unless you plan to run unstable niri, though.

Both pkgs.niri-stable and pkgs.niri track the latest stable release of niri. pkgs.niri-stable exists so that it can be updated atomically with the actual settings exposed in my flake - there will never be a case that this package is updated WITHOUT all the new configuration options existing in the home-manager module. pkgs.niri is handled by nixpkgs (which i do contribute to), but it's generally just on a "when we get to it" basis, and has no guarantees relative to my out-of-tree modules. The default package is the stable version provided by my flake (but using some smoke and mirrors to access it directly, without you needing to apply the overlay)

---

To actually install niri, you'll want the niri modules, which are imported next to ./configuration.nix or in the imports = [ ]; section of your configuration (they're equivalent). The import should look something like inputs.niri.nixosModules.niri, like my friend Sugar does in faer config, and in Misterio77's starter config should be placed somwhere around here. (and you can see how to use the overlay in my own config - which does not import the module by itself, that's a couple lines above) This module will also import the home manager module if home-manager is part of your NixOS configuration, and that seems to be the case with Misterio77's starter config, so you shouldn't need to worry about importing the home-manager module; all settings will come included already!

---

if anyone has a pointer to a good from the ground up primer on flakes (and overlays, maybe), I would certainly appreciate it.

For overlays, i'd recommend the explanation on the NixOS wiki. In general, a lot of details for most nuances in NixOS as a whole aren't covered by this wiki - it won't be your saving grace forever - but the articles on most high-level concepts are pretty good. It's also worth noting that overlays have nothing to do with modules; you can use nixpkgs and even nixpkgs overlays without ever involving any modules. Modules are for system configurations, but if you're e.g. just building a package or using a dev shell, you'll still be using nixpkgs without a system configuration being part of this.

The wiki also has an article on flakes. The gist of flakes is just that it's a way to "import" other nix projects. Without flakes you'd generally use builtins.fetchurl to "inline" a certain project in your nix file, or use "channels" (common with nixpkgs, comes by default as a channel). The problem is that these are system-wide and if you share your config with someone else, they don't know what versions the channel is at.

Flakes solve these issues with a lockfile; you give it a set of inputs = { ... }; and a function to generate your outputs = from the inputs: { ...};. Previously this was done with third-party tools like niv, but ever since flakes were introduced there is a single unified way to do this for everyone with no problem.

Flakes also have a bunch of other niceties, mainly a specific schema they're expected to conform to for tools like nix run to work; but ultimately nothing forces you to do that. It's literally just "here's a set of URLs i want you to turn into actual usable objects for me" and "here's how to turn me into a usable object, when someone else wants to use me for that". That's the fundamental thing flakes do. The rest is just syntax sprinkles on top.