From ac4fd32e2b1596d8d33c3c3a06a86ebf63a30fab Mon Sep 17 00:00:00 2001
From: Daniel Fainberg <mail@daniel.fainberg.net>
Date: Thu, 6 Aug 2026 09:13:29 +0200
Subject: [PATCH] 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>
---
 README.md | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 9fa7fd3..6afaa52 100644
--- a/README.md
+++ b/README.md
@@ -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.