From 59869deebb77407c858ae7b13d8dde810e617840 Mon Sep 17 00:00:00 2001
From: projectmoon <projectmoon@agnos.is>
Date: Wed, 1 Mar 2023 07:42:34 +0100
Subject: [PATCH] Documentation updates about how to use the overlay
 (quickstart coming soon)

---
 README.md | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5398417..0dadc3a 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@ Individual packages can be unmasked (and added to
 ```
 sys-kernel/libre-kernel::projectmoon
 virtual/dist-kernel::projectmoon
+sec-keys/openpgp-keys-linux-libre::projectmoon
 ```
 
 ## The Linux-libre dist-kernel
@@ -58,6 +59,41 @@ package is not found at all, like normal dist-kernel ebuilds.
 The kernel installed by this ebuild has the version suffix
 `-gnu-dist`, making it easy to determine which kernel it is.
 
+
+### Signature Verification
+
+It is recommended to enable GPG signature verification of
+`sys-kenrel/libre-kernel` by adding the USE flag to
+`/etc/portage/package.use`:
+
+```
+sys-kernel/libre-kernel verify-sig
+```
+
+### Keeping the Linux-libre Kernel Installed
+
+Portage will sometimes try to install `sys-kernel/gentoo-kernel` or
+another dist-kernel if there is a newer stable version than
+`sys-kernel/libre-kernel`. This happens because of a version bump to
+`virtual/dist-kernel` before this overlay has updated its own copy of
+`virtual/dist-kernel`.
+
+To prevent portage from attempting to install another dist-kernel
+instead of the Linux-libre kernel, you should mask other dist-kernels in
+`/etc/portage/package.mask`:
+
+```
+# stay on libre kernel
+sys-kernel/gentoo-kernel
+sys-kernel/gentoo-kernel-bin
+sys-kernel/vanilla-kernel
+```
+
+### Linux Firmware
+
+*Note: If you are running the Linux-libre kernel, it is unlikely (though
+not impossible) that you need to install `sys-kernel/linux-firmware`.*
+
 To install only the Linux firmware that meets the [Free Software
 Definition][free-software], configure `/etc/portage/package.use`
 accordingly:
@@ -87,9 +123,9 @@ This ebuild supports the `dist-kernel` USE flag, and the module will
 automatically be rebuilt when installing a new dist-kernel if that
 flag is enabled.
 
-If you are not using a dist-kernel, when upgrading or installing a new
-kernel, you will need to do `emerge @modules-rebuild` to install the
-module for the new kernel.
+If you are not using a dist-kernel, you will need to do `emerge
+@modules-rebuild` to install the module after you upgrade or install a
+new kernel,
 
 ### Librem Control and the Purism EC Tool