diff --git a/doc/using/configuration.chapter.md b/doc/using/configuration.chapter.md
index 252d255de829..05a8fa5517cc 100644
--- a/doc/using/configuration.chapter.md
+++ b/doc/using/configuration.chapter.md
@@ -1,6 +1,7 @@
 # Global configuration {#chap-packageconfig}
 
-Nix comes with certain defaults about what packages can and cannot be installed, based on a package's metadata. By default, Nix will prevent installation if any of the following criteria are true:
+Nix comes with certain defaults about which packages can and cannot be installed, based on a package's metadata.
+By default, Nix will prevent installation if any of the following criteria are true:
 
 -   The package is thought to be broken, and has had its `meta.broken` set to `true`.
 
@@ -10,23 +11,14 @@ Nix comes with certain defaults about what packages can and cannot be installed,
 
 -   The package has known security vulnerabilities but has not or can not be updated for some reason, and a list of issues has been entered in to the package's `meta.knownVulnerabilities`.
 
-Note that all this is checked during evaluation already, and the check includes any package that is evaluated. In particular, all build-time dependencies are checked. `nix-env -qa` will (attempt to) hide any packages that would be refused.
+Each of these criteria can be altered in the Nixpkgs configuration.
 
-Each of these criteria can be altered in the nixpkgs configuration.
+:::{.note}
+All this is checked during evaluation already, and the check includes any package that is evaluated.
+In particular, all build-time dependencies are checked.
+:::
 
-The nixpkgs configuration for a NixOS system is set in the `configuration.nix`, as in the following example:
-
-```nix
-{
-  nixpkgs.config = {
-    allowUnfree = true;
-  };
-}
-```
-
-However, this does not allow unfree software for individual users. Their configurations are managed separately.
-
-A user's nixpkgs configuration is stored in a user-specific configuration file located at `~/.config/nixpkgs/config.nix`. For example:
+A user's Nixpkgs configuration is stored in a user-specific configuration file located at `~/.config/nixpkgs/config.nix`. For example:
 
 ```nix
 {
@@ -34,7 +26,10 @@ A user's nixpkgs configuration is stored in a user-specific configuration file l
 }
 ```
 
-Note that we are not able to test or build unfree software on Hydra due to policy. Most unfree licenses prohibit us from either executing or distributing the software.
+:::{.caution}
+Unfree software is not tested or built in Nixpkgs continuous integration, and therefore not cached.
+Most unfree licenses prohibit either executing or distributing the software.
+:::
 
 ## Installing broken packages {#sec-allow-broken}
 
diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md
index a524ef266eaf..074932b3f110 100644
--- a/nixos/doc/manual/configuration/customizing-packages.section.md
+++ b/nixos/doc/manual/configuration/customizing-packages.section.md
@@ -1,11 +1,33 @@
 # Customising Packages {#sec-customising-packages}
 
-Some packages in Nixpkgs have options to enable or disable optional
-functionality or change other aspects of the package.
+The Nixpkgs configuration for a NixOS system is set by the {option}`nixpkgs.config` option.
+
+::::{.example}
+# Globally allow unfree packages
+
+```nix
+{
+  nixpkgs.config = {
+    allowUnfree = true;
+  };
+}
+```
+
+:::{.note}
+This only allows unfree software in the given NixOS configuration.
+For users invoking Nix commands such as [`nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build), Nixpkgs is configured independently.
+See the [Nixpkgs manual section on global configuration](https://nixos.org/manual/nixpkgs/unstable/#chap-packageconfig) for details.
+:::
+::::
+
+<!-- TODO(@fricklerhandwerk)
+all of the following should go to the Nixpkgs manual, it has nothing to do with NixOS
+-->
+
+Some packages in Nixpkgs have options to enable or disable optional functionality, or change other aspects of the package.
 
 ::: {.warning}
-Unfortunately, Nixpkgs currently lacks a way to query available
-configuration options.
+Unfortunately, Nixpkgs currently lacks a way to query available package configuration options.
 :::
 
 ::: {.note}