lib: simplify bootstrapping

Previously, `lib/top-level.nix` used an `_isExtended` flag to indicate
whether the provided `lib` was already extended. This made bootstrapping
unclear and introduced the possibility of circular construction.

All construction now flows through the lib-overlay, removing
`_isExtended`. As a result, `lib/top-level.nix` always receives the
final extended lib.

The `<flake>.lib.nixvim` output is now defined as:

    (lib.extend <nixvim>.lib.overlay).nixvim

The overlay now imports `top-level.nix` directly, making it the
canonical entrypoint for constructing Nixvim's section of the lib.

A clarifying doccomment was added to `lib/top-level.nix`.

flake/lib.nix

@@ -13,9 +13,8 @@
 
   # Public `lib` flake output
   flake.lib = {
-    nixvim = lib.makeOverridable (import ../lib/top-level.nix) {
+    nixvim = lib.makeOverridable ({ lib }: (lib.extend self.lib.overlay).nixvim) {
       inherit lib;
-      flake = self;
     };
     overlay = lib.makeOverridable (import ../lib/overlay.nix) {
       flake = self;

lib/overlay.nix

@@ -27,10 +27,7 @@
 */
 lib: prevLib: {
   # Add Nixvim's section to the lib
-  nixvim = flake.lib.nixvim.override {
-    inherit lib;
-    _isExtended = true;
-  };
+  nixvim = import ./top-level.nix { inherit flake lib; };
 
   # Extend the maintainers set with Nixvim-specific maintainers
   maintainers = prevLib.maintainers // import ./maintainers.nix;

lib/top-level.nix

@@ -1,17 +1,33 @@
+/**
+  Construct Nixvim's section of the lib: `lib.nixvim`.
+
+  This function requires the final extended lib (as produced by `./overlay.nix`)
+  and should not usually be imported directly.
+
+  The flake output `<nixvim>.lib.nixvim` provides an instance of Nixvim's lib section.
+
+  # Inputs
+
+  `flake`
+  : The nixvim flake.
+
+  `lib`
+  : The final extended lib.
+*/
 {
   lib,
   flake,
-  _isExtended ? false,
 }:
 lib.makeExtensible (
   self:
   let
     # Used when importing parts of our lib
     call = lib.callPackageWith {
-      inherit call self;
-      # TODO: this would be much simpler if `lib` & `self` were kept explicitly separate
-      # Doing so should also improve overridability and simplify bootstrapping.
-      lib = if _isExtended then lib else lib.extend flake.lib.overlay;
+      inherit
+        call
+        self
+        lib
+        ;
     };
   in
   {