docs(readme): advertise decoupled consumption, rename input to baseline

default the consumer example to owning its own `nixpkgs` (with the baseline
following it) so a consumer's update cadence stays theirs; keep the coupled
`follows` form as a quickstart alternative. rename the `pub` input to
`baseline`, and note that `local.*` options double as the override for
deliberately-frozen pins.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-08-06 09:13:29 +02:00
co-authored by Claude Opus 4.8
parent b9a5cd1a95
commit ac4fd32e2b
+23 -8
View File
@@ -33,7 +33,7 @@ keeps it.
```
your-inventory/
├── flake.nix # inputs (pub + follows) + nixosConfigurations.<host>
├── flake.nix # inputs (baseline + your nixpkgs) + nixosConfigurations.<host>
├── flake.lock
├── system/ # system-level modules
│ ├── regional.nix # time zone / keymap / locale (see Overriding)
@@ -55,17 +55,22 @@ The `flake.nix` that wires it together:
```nix
{
inputs = {
pub.url = "github:<owner>/<repo>";
# Reuse the public flake's pins so versions never drift between the two.
nixpkgs.follows = "pub/nixpkgs";
home-manager.follows = "pub/home-manager";
# You own nixpkgs, so your update cadence is yours — the baseline modules
# build against the versions you pin here.
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
baseline.url = "github:<owner>/<repo>";
baseline.inputs.nixpkgs.follows = "nixpkgs"; # baseline builds against YOUR nixpkgs
baseline.inputs.home-manager.follows = "home-manager";
};
outputs = inputs@{ self, nixpkgs, pub, home-manager, ... }: {
outputs = inputs@{ self, nixpkgs, baseline, home-manager, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
pub.nixosModules.default # generic system baseline
baseline.nixosModules.default # generic system baseline
./system/regional.nix # your regional values (see below)
./hosts/myhost # hardware + hostname
home-manager.nixosModules.home-manager
@@ -75,7 +80,7 @@ The `flake.nix` that wires it together:
# Inject your own inputs into your home modules; the public ones ignore them.
home-manager.extraSpecialArgs = { inherit inputs; };
home-manager.users.me.imports = [
pub.homeModules.default # generic home baseline
baseline.homeModules.default # generic home baseline
./home/identity.nix # your git identity, name/email, …
./home/ssh.nix # your SSH hosts (topology stays private)
# … more personal home modules
@@ -87,6 +92,12 @@ The `flake.nix` that wires it together:
}
```
This repo ships *modules*, not pinned packages: they build against the `nixpkgs` **you**
declare above, so you decide when packages move. *Quickstart alternative:* drop your own
`nixpkgs` and write `nixpkgs.follows = "baseline/nixpkgs"` to pin to this repo's tested
versions instead — one less thing to think about, but then your update cadence is whatever
this repo pins, not the reverse.
Your machine list, hostnames, and any private specifics stay in *your* flake — you pull
only the generic modules from here.
@@ -111,6 +122,10 @@ from your private flake, in rough order of how often you reach for them:
local.texlive.package = pkgs.texlive.withPackages (ps: [ ps.scheme-full ]);
```
A few `local.*` options exist precisely because a module pins a package to a nixpkgs
*other* than the one you declare (a deliberate freeze that would otherwise reach you
regardless of your own pin); the option is how you pull it back onto your nixpkgs.
3. **Extra modules.** Anything with no public counterpart is just another module in the
import lists above — personal apps, SSH/Syncthing topology, secrets wiring.