From ac5df335babfc62696314b4ddd16b02dacfb54b6 Mon Sep 17 00:00:00 2001
From: ibizaman <ibizaman@tiserbox.com>
Date: Mon, 27 Oct 2025 22:45:08 +0100
Subject: [PATCH] doc: better info on how to setup selfhostblocks

---
 docs/redirects.json |  4 +--
 docs/usage.md       | 77 ++++++++++++++++++++++++++++++---------------
 2 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/docs/redirects.json b/docs/redirects.json
index 5da3119..fe8f736 100644
--- a/docs/redirects.json
+++ b/docs/redirects.json
@@ -4010,8 +4010,8 @@
   "usage-flake-autoupdate": [
     "usage.html#usage-flake-autoupdate"
   ],
-  "usage-flake-nixpkgs": [
-    "usage.html#usage-flake-nixpkgs"
+  "usage-flake-lib": [
+    "usage.html#usage-flake-lib"
   ],
   "usage-flake-substituter": [
     "usage.html#usage-flake-substituter"
diff --git a/docs/usage.md b/docs/usage.md
index f5ea5f8..e0875d9 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -27,6 +27,57 @@ imports = [
 ];
 ```
 
+Self Host Blocks provides its own `pkgs.lib` and `nixpkgs`.
+It is required to use the provided ones as input for your deployments,
+otherwise you might end up blocked when Self Host Blocks patches a module, function or package.
+You need the following code wherever you would usually import `nixpkgs`:
+
+```nix
+{
+  inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks";
+
+  outputs = { selfhostblocks, ... }: let
+    system = "x86_64-linux";
+
+    shb = selfhostblocks.lib.${system};
+
+    nixpkgs' = import shb.nixpkgs {
+      inherit system;
+    };
+  in
+    nixosConfigurations = {
+      myserver = shb.pkgs.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          ./configuration.nix
+        ];
+      };
+    };
+
+    // elsewhere where nixpkgs is needed:
+}
+```
+
+### SHB Lib {#usage-flake-lib}
+
+Providing patches to downstream users is finicky, to say the least.
+For example, using `selfhostblocks.inputs.nixpkgs` directly will _not_ work.
+So Self Host Blocks provides a few attributes under the `selfhostblocks.lib.${system}` flake output:
+
+- At the top-level, all functions defined by SHB under [`./lib/default.nix`](@REPO@/lib/default.nix) and [`./test/common.nix`](@REPO@/test/common.nix).
+- `patches`: the list of patches applied by SHB [`./patches`](@REPO@/patches) to nixpkgs.
+- `contracts`: all contract modules.
+- `patchNixpkgs`: a re-export of `nixpkgs.legacyPackages.${system}.applyPatches` with the arguments made a bit more explicit.
+- `patchedNixpkgs`: nixpkgs with `patches` applied.
+- `pkgs`: `nixpkgs.legacyPackages.${system}` with `patches` applied and also:
+   - `config.allowUnfree` set to `true`
+   - `lib.shb` holds functions defined by [`./lib/default.nix`](@REPO@/lib/default.nix)
+   - `lib.evalModules` is patched to include patches provided by nixpkgs
+   - `nixosSystem` is patched to include patches provided by nixpkgs
+
+For normal usage, one should only need `selfhostblocks.lib.${system}.pkgs`
+and in some cases `selfhostblocks.lib.${system}.nixpkgs`.
+
 ### Substituter {#usage-flake-substituter}
 
 You can also use the public cache as a substituter with:
@@ -41,32 +92,6 @@ nix.settings.substituters = [
 ];
 ```
 
-### Follow Nixpkgs {#usage-flake-nixpkgs}
-
-Self Host Blocks provides its own `nixpkgs` input so both can be updated in lock step, ensuring
-maximum compatibility. It is recommended to use the following `nixpkgs` as input for your
-deployments. Also, patches can be applied by Self Host Blocks. To handle all this, you need the
-following code instead wherever you import `nixpkgs`:
-
-```nix
-{
-  inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks";
-
-  outputs = { selfhostblocks, ... }: let
-    system = "x86_64-linux";
-    lib = selfhostblocks.lib.${system};
-
-    nixpkgs' = lib.shb.patchedNixpkgs;
-
-    shbNixpkgs = import nixpkgs' {
-      inherit system;
-    };
-  in
-```
-
-Advanced users can if they wish use a version of `nixpkgs` of their choosing but then we cannot
-guarantee Self Host Block won't use a non-existing option from `nixpkgs`.
-
 ### Tag Updates {#usage-flake-tag}
 
 To pin Self Host Blocks to a release/tag, run the following snippet: