From 0c3de27f411c25be6a57596e676f95789be2ee02 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Sun, 19 Oct 2025 17:21:42 +0300
Subject: [PATCH 01/20] fix(meta): fail fast on missing app and role modules

---
 modules/meta/nixos-app-helpers.nix | 18 ++++++++++++++----
 modules/roles/desktop.nix          | 19 +++++++++++++------
 modules/roles/xserver.nix          | 20 ++------------------
 modules/system76/imports.nix       | 14 +++++++++-----
 modules/workstation.nix            | 14 +++++++-------
 5 files changed, 45 insertions(+), 40 deletions(-)

diff --git a/modules/meta/nixos-app-helpers.nix b/modules/meta/nixos-app-helpers.nix
index b6e3aec30..1fb27eb7c 100644
--- a/modules/meta/nixos-app-helpers.nix
+++ b/modules/meta/nixos-app-helpers.nix
@@ -87,7 +87,12 @@ let
             (lib.nameValuePair appName (lib.getAttrFromPath path imported))
           ]
         else
-          acc
+          throw (
+            "nixos-app-helpers: expected "
+            + toString filePath
+            + " to export flake.nixosModules.apps."
+            + appName
+          )
     else
       acc
   ) { } appFiles;
@@ -120,16 +125,21 @@ let
               if lib.hasAttrByPath path imported then
                 lib.getAttrFromPath path imported
               else
-                lib.trace "nixos-app-helpers: app module missing path ${builtins.concatStringsSep "." path}" null
+                throw (
+                  "nixos-app-helpers: app module missing path "
+                  + builtins.concatStringsSep "." path
+                )
             else
-              lib.trace "nixos-app-helpers: missing app file ${toString maybeFile}" null;
+              throw (
+                "nixos-app-helpers: missing app file " + toString maybeFile
+              );
           previewList = lib.take 20 appKeys;
           preview = lib.concatStringsSep ", " previewList;
           ellipsis = if lib.length appKeys > 20 then ", …" else "";
           suggestion = if appKeys == [ ] then "" else " Known keys (partial): ${preview}${ellipsis}";
         in
         if fallbackModule != null then
-          lib.trace "nixos-app-helpers: fallback loaded ${name}" fallbackModule
+          fallbackModule
         else
           throw ("Unknown NixOS app '" + name + "'" + suggestion);
 
diff --git a/modules/roles/desktop.nix b/modules/roles/desktop.nix
index 43a99c8e2..c8e60ae2c 100644
--- a/modules/roles/desktop.nix
+++ b/modules/roles/desktop.nix
@@ -11,8 +11,18 @@ let
   getApp = rawHelpers.getApp or fallbackGetApp;
   getApps = rawHelpers.getApps or (names: map getApp names);
 
-  xserverRole = lib.attrByPath [ "roles" "xserver" ] config.flake.nixosModules null;
-  i3Module = lib.attrByPath [ "window-manager" "i3" ] config.flake.nixosModules null;
+  xserverRolePath = [ "roles" "xserver" ];
+  xserverRole =
+    if lib.hasAttrByPath xserverRolePath config.flake.nixosModules then
+      lib.getAttrFromPath xserverRolePath config.flake.nixosModules
+    else
+      throw "Desktop role requires flake.nixosModules.roles.xserver";
+  i3ModulePath = [ "window-manager" "i3" ];
+  i3Module =
+    if lib.hasAttrByPath i3ModulePath config.flake.nixosModules then
+      lib.getAttrFromPath i3ModulePath config.flake.nixosModules
+    else
+      throw "Desktop role requires flake.nixosModules.window-manager.i3";
 
   desktopApps = [
     "blueberry"
@@ -29,10 +39,7 @@ let
     "udiskie"
   ];
 
-  roleImports =
-    lib.optionals (xserverRole != null) [ xserverRole ]
-    ++ lib.optionals (i3Module != null) [ i3Module ]
-    ++ getApps desktopApps;
+  roleImports = [ xserverRole i3Module ] ++ getApps desktopApps;
 in
 {
   flake.nixosModules.roles.desktop.imports = roleImports;
diff --git a/modules/roles/xserver.nix b/modules/roles/xserver.nix
index 2a8432999..ad5eecc64 100644
--- a/modules/roles/xserver.nix
+++ b/modules/roles/xserver.nix
@@ -23,26 +23,10 @@ let
         throw ("Unknown NixOS app '" + name + "' (role xserver)");
   getApp =
     name:
-    let
-      tryRaw =
-        if rawHelpers ? getApp then
-          builtins.tryEval (rawHelpers.getApp name)
-        else
-          {
-            success = false;
-            value = null;
-          };
-    in
-    if tryRaw.success then tryRaw.value else fallbackGetApp name;
+    if rawHelpers ? getApp then rawHelpers.getApp name else fallbackGetApp name;
   getApps =
     names:
-    if rawHelpers ? getApps then
-      let
-        attempt = builtins.tryEval (rawHelpers.getApps names);
-      in
-      if attempt.success then attempt.value else map getApp names
-    else
-      map getApp names;
+    if rawHelpers ? getApps then rawHelpers.getApps names else map getApp names;
   i3SessionModule =
     { pkgs, lib, ... }:
     {
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index 61043ae36..915463cb4 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -15,15 +15,19 @@ let
     name:
     let
       getRole = roleHelpers.getRole or (_: null);
-      attempt = builtins.tryEval (getRole name);
+      roleValue = getRole name;
     in
-    if attempt.success && attempt.value != null then
-      attempt.value
+    if roleValue != null then
+      roleValue
     else if lib.hasAttrByPath [ "roles" name ] nixosModules then
       lib.getAttrFromPath [ "roles" name ] nixosModules
     else
-      null;
-  roleModules = lib.filter (module: module != null) (map getRoleModule roleNames);
+      throw (
+        "system76 host requires role "
+        + name
+        + " but it was not found in helpers or flake.nixosModules"
+      );
+  roleModules = map getRoleModule roleNames;
   getVirtualizationModule =
     name:
     if lib.hasAttrByPath [ "virtualization" name ] nixosModules then
diff --git a/modules/workstation.nix b/modules/workstation.nix
index bf66fc018..9a70e4902 100644
--- a/modules/workstation.nix
+++ b/modules/workstation.nix
@@ -11,8 +11,7 @@ let
   resolveRoleOption =
     name:
     let
-      candidateEval = builtins.tryEval (rawResolveRole name);
-      candidate = if candidateEval.success then candidateEval.value else null;
+      candidate = rawResolveRole name;
       namePath = lib.splitString "." name;
       rolePath = [ "roles" ] ++ namePath;
 
@@ -20,9 +19,9 @@ let
         attrs:
         if lib.hasAttrByPath rolePath attrs then
           let
-            valueEval = builtins.tryEval (lib.getAttrFromPath rolePath attrs);
+            value = lib.getAttrFromPath rolePath attrs;
           in
-          if valueEval.success then valueEval.value else null
+          value
         else
           null;
 
@@ -144,9 +143,10 @@ in
       if missingRoleNames == [ ] then
         importsValue
       else
-        lib.warn (
-          "Skipping unavailable workstation roles: " + lib.concatStringsSep ", " missingRoleNames
-        ) importsValue;
+        throw (
+          "workstation bundle requires roles that failed to resolve: "
+          + lib.concatStringsSep ", " missingRoleNames
+        );
     config = lib.mkIf (hmGuiModule != null) (
       let
         extraNames = lib.attrByPath [ "home-manager" "extraAppImports" ] [ ] config;

From e66663a4f96d1e5145983c68a4739fc15b1d58e4 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Sun, 19 Oct 2025 17:33:06 +0300
Subject: [PATCH 02/20] fix(runtime): surface hidden activation errors

---
 modules/hardware/monitors/lenovo-y27q-20.nix | 34 ++++++++++++-----
 modules/home/pass-secret-service.nix         |  4 +-
 modules/services/duplicati-r2.nix            | 40 ++++++++++++++++----
 modules/system76/usbguard.nix                | 12 +++++-
 4 files changed, 69 insertions(+), 21 deletions(-)

diff --git a/modules/hardware/monitors/lenovo-y27q-20.nix b/modules/hardware/monitors/lenovo-y27q-20.nix
index 48e4ffd53..1fe94cd3d 100644
--- a/modules/hardware/monitors/lenovo-y27q-20.nix
+++ b/modules/hardware/monitors/lenovo-y27q-20.nix
@@ -49,7 +49,10 @@ let
         # Prefer EDID-based match so connectors (HDMI, DP, USB-C) do not matter
         while IFS= read -r dev; do
           [ -z "$dev" ] && continue
-          info="$($COLORMGR get-device "$dev" 2>/dev/null || true)"
+          if ! info="$($COLORMGR get-device "$dev" 2>/dev/null)"; then
+            echo "lenovo-y27q-20: failed to query device $dev" >&2
+            exit 1
+          fi
           vendor=$(trim "$(printf '%s\n' "$info" | sed -n 's/^\s*Vendor:\s*//p' | head -n1)")
           model=$(trim "$(printf '%s\n' "$info" | sed -n 's/^\s*Model:\s*//p' | head -n1)")
           serial=$(trim "$(printf '%s\n' "$info" | sed -n 's/^\s*Serial:\s*//p' | head -n1)")
@@ -70,11 +73,11 @@ let
 
           device_path="$dev"
           break
-        done < <($COLORMGR get-devices-by-kind display 2>/dev/null || true)
+        done < <($COLORMGR get-devices-by-kind display 2>/dev/null)
 
         if [ -z "$device_path" ]; then
           for candidate in ${lib.concatStringsSep " " (map lib.escapeShellArg candidateIds)}; do
-            if path="$($COLORMGR find-device "$candidate" 2>/dev/null)"; then
+            if path="$($COLORMGR find-device $candidate 2>/dev/null)"; then
               device_path="$path"
               break
             fi
@@ -83,13 +86,20 @@ let
 
         if [ -z "$device_path" ]; then
           echo "lenovo-y27q-20: no matching colord display device found" >&2
-          exit 0
+          exit 1
         fi
 
-        profile_id="$($COLORMGR find-profile-by-filename "$PROFILE_PATH" 2>/dev/null || true)"
+        if ! profile_id="$($COLORMGR find-profile-by-filename "$PROFILE_PATH" 2>/dev/null)"; then
+          profile_id=""
+        fi
         if [ -z "$profile_id" ]; then
-          $COLORMGR import-profile "$PROFILE_PATH" >/dev/null 2>&1 || true
-          profile_id="$($COLORMGR find-profile-by-filename "$PROFILE_PATH" 2>/dev/null || true)"
+          if ! $COLORMGR import-profile "$PROFILE_PATH" >/dev/null 2>&1; then
+            echo "lenovo-y27q-20: failed to import profile $PROFILE_PATH" >&2
+            exit 1
+          fi
+          if ! profile_id="$($COLORMGR find-profile-by-filename "$PROFILE_PATH" 2>/dev/null)"; then
+            profile_id=""
+          fi
         fi
 
         if [ -z "$profile_id" ]; then
@@ -98,8 +108,14 @@ let
         fi
 
         if ! $COLORMGR device-get-default-profile "$device_path" | grep -F "$profile_id" >/dev/null 2>&1; then
-          $COLORMGR device-add-profile "$device_path" "$profile_id" >/dev/null 2>&1 || true
-          $COLORMGR device-make-profile-default "$device_path" "$profile_id" >/dev/null 2>&1 || true
+          if ! $COLORMGR device-add-profile "$device_path" "$profile_id" >/dev/null 2>&1; then
+            echo "lenovo-y27q-20: failed to add profile $PROFILE_PATH to $device_path" >&2
+            exit 1
+          fi
+          if ! $COLORMGR device-make-profile-default "$device_path" "$profile_id" >/dev/null 2>&1; then
+            echo "lenovo-y27q-20: failed to set $PROFILE_PATH as default for $device_path" >&2
+            exit 1
+          fi
         fi
       '';
     in
diff --git a/modules/home/pass-secret-service.nix b/modules/home/pass-secret-service.nix
index 24a85fc0c..300c4dae5 100644
--- a/modules/home/pass-secret-service.nix
+++ b/modules/home/pass-secret-service.nix
@@ -24,7 +24,7 @@
             if [ -r "$key_file" ]; then
               if ! gpg --batch --list-secret-keys ${keyFingerprint} >/dev/null 2>&1; then
                 gpg --batch --yes --import "$key_file"
-                echo "5\ny\n" | gpg --batch --yes --command-fd 0 --edit-key ${keyFingerprint} trust quit >/dev/null 2>&1 || true
+                echo "5\ny\n" | gpg --batch --yes --command-fd 0 --edit-key ${keyFingerprint} trust quit >/dev/null 2>&1
               fi
             fi
           ''
@@ -33,7 +33,7 @@
         activation.initPassStore = lib.mkIf haveKeyPath (
           lib.hm.dag.entryAfter [ "importPassGpgKey" ] ''
             if [ ! -d "$HOME/.password-store" ]; then
-              pass init --quiet ${keyFingerprint} || true
+              pass init --quiet ${keyFingerprint}
             fi
           ''
         );
diff --git a/modules/services/duplicati-r2.nix b/modules/services/duplicati-r2.nix
index 6b9dd0f1c..597810dbc 100644
--- a/modules/services/duplicati-r2.nix
+++ b/modules/services/duplicati-r2.nix
@@ -465,11 +465,23 @@ let
                           local base
                           base="$(basename "$unit")"
                           if [[ "$base" == *.timer ]]; then
-                            systemctl stop "$base" 2>/dev/null || true
-                            systemctl disable --runtime "$base" 2>/dev/null || true
+                            if ! systemctl stop "$base" 2>/dev/null; then
+                              echo "duplicati-r2 generator: failed to stop $base" >&2
+                              exit 1
+                            fi
+                            if ! systemctl disable --runtime "$base" 2>/dev/null; then
+                              echo "duplicati-r2 generator: failed to disable $base" >&2
+                              exit 1
+                            fi
                           elif [[ "$base" == *.service ]]; then
-                            systemctl stop "$base" 2>/dev/null || true
-                            systemctl disable --runtime "$base" 2>/dev/null || true
+                            if ! systemctl stop "$base" 2>/dev/null; then
+                              echo "duplicati-r2 generator: failed to stop $base" >&2
+                              exit 1
+                            fi
+                            if ! systemctl disable --runtime "$base" 2>/dev/null; then
+                              echo "duplicati-r2 generator: failed to disable $base" >&2
+                              exit 1
+                            fi
                           fi
                           rm -f "$unit"
                         fi
@@ -619,13 +631,25 @@ let
                     systemctl daemon-reload
 
                     for timer in "''${backup_timers[@]}"; do
-                      systemctl enable --runtime "$timer" >/dev/null 2>&1 || true
-                      systemctl start "$timer" >/dev/null 2>&1 || true
+                      if ! systemctl enable --runtime "$timer" >/dev/null 2>&1; then
+                        echo "duplicati-r2 generator: failed to enable $timer" >&2
+                        exit 1
+                      fi
+                      if ! systemctl start "$timer" >/dev/null 2>&1; then
+                        echo "duplicati-r2 generator: failed to start $timer" >&2
+                        exit 1
+                      fi
                     done
 
                     for timer in "''${verify_timers[@]}"; do
-                      systemctl enable --runtime "$timer" >/dev/null 2>&1 || true
-                      systemctl start "$timer" >/dev/null 2>&1 || true
+                      if ! systemctl enable --runtime "$timer" >/dev/null 2>&1; then
+                        echo "duplicati-r2 generator: failed to enable $timer" >&2
+                        exit 1
+                      fi
+                      if ! systemctl start "$timer" >/dev/null 2>&1; then
+                        echo "duplicati-r2 generator: failed to start $timer" >&2
+                        exit 1
+                      fi
                     done
         '';
       };
diff --git a/modules/system76/usbguard.nix b/modules/system76/usbguard.nix
index 1a655d383..ac2ada7f5 100644
--- a/modules/system76/usbguard.nix
+++ b/modules/system76/usbguard.nix
@@ -11,8 +11,16 @@ let
       flakeLib = libAttrs.flake or { };
       securityLib = (flakeLib.lib or { }).security or { };
     in
-    securityLib.usbguard or { };
-  baseRules = lib.strings.trim (usbguardLib.baseRules or "");
+    if securityLib ? usbguard then
+      securityLib.usbguard
+    else
+      throw "system76/usbguard: securityLib.usbguard missing; ensure usbguard-lib exports the helper";
+  baseRulesRaw = usbguardLib.baseRules or null;
+  baseRules =
+    if baseRulesRaw == null || lib.strings.trim baseRulesRaw == "" then
+      throw "system76/usbguard: baseRules is empty; populate usbguardLib.baseRules"
+    else
+      lib.strings.trim baseRulesRaw;
   baseRulesFile = pkgs.writeText "usbguard-base.rules" baseRules;
   defaultsModule = usbguardLib.defaultsModule or null;
   moduleImports = lib.optional (defaultsModule != null) defaultsModule;

From 29e2f175e1d136053f4be9438201d8b8353284e0 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Sun, 19 Oct 2025 18:11:07 +0300
Subject: [PATCH 03/20] fix: incorrect naming for modules/apps

---
 modules/apps/kiro-fhs.nix        |  2 +-
 modules/apps/vscode-fhs.nix      |  2 +-
 modules/apps/wappalyzer-next.nix | 22 +++++++++++++++-------
 modules/roles/dev.nix            |  4 ++--
 modules/roles/warp-client.nix    |  2 +-
 5 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/modules/apps/kiro-fhs.nix b/modules/apps/kiro-fhs.nix
index a49de467b..abfb31f80 100644
--- a/modules/apps/kiro-fhs.nix
+++ b/modules/apps/kiro-fhs.nix
@@ -19,7 +19,7 @@
 
 {
   # App module that installs Kiro (FHS) when imported
-  flake.nixosModules.apps.kiroFhs =
+  flake.nixosModules.apps."kiro-fhs" =
     { pkgs, ... }:
     {
       # Allow unfree if required by kiro-fhs packaging
diff --git a/modules/apps/vscode-fhs.nix b/modules/apps/vscode-fhs.nix
index 7071c08a0..f33be6830 100644
--- a/modules/apps/vscode-fhs.nix
+++ b/modules/apps/vscode-fhs.nix
@@ -23,7 +23,7 @@
 
 {
   # App module that installs VS Code (FHS) when imported
-  flake.nixosModules.apps.vscodeFhs =
+  flake.nixosModules.apps."vscode-fhs" =
     { pkgs, ... }:
     {
       nixpkgs.allowedUnfreePackages = [
diff --git a/modules/apps/wappalyzer-next.nix b/modules/apps/wappalyzer-next.nix
index 8336c0dc7..cb44d6f69 100644
--- a/modules/apps/wappalyzer-next.nix
+++ b/modules/apps/wappalyzer-next.nix
@@ -12,11 +12,19 @@
 */
 
 _: {
-  flake.homeManagerModules.apps."wappalyzer-next" =
-    { pkgs, config, ... }:
-    {
-      home.packages = [
-        config.flake.packages.${pkgs.system}.wappalyzer-next
-      ];
-    };
+  flake = {
+    nixosModules.apps."wappalyzer-next" =
+      { pkgs, ... }:
+      {
+        environment.systemPackages = [ pkgs.wappalyzer-next ];
+      };
+
+    homeManagerModules.apps."wappalyzer-next" =
+      { pkgs, config, ... }:
+      {
+        home.packages = [
+          config.flake.packages.${pkgs.system}.wappalyzer-next
+        ];
+      };
+  };
 }
diff --git a/modules/roles/dev.nix b/modules/roles/dev.nix
index 2ae5649e5..7cbb93252 100644
--- a/modules/roles/dev.nix
+++ b/modules/roles/dev.nix
@@ -44,8 +44,8 @@ let
     "yarn"
     "nrm"
     # FHS-based dev tools
-    "vscodeFhs"
-    "kiroFhs"
+    "vscode-fhs"
+    "kiro-fhs"
   ];
   roleImports = getApps devApps;
 in
diff --git a/modules/roles/warp-client.nix b/modules/roles/warp-client.nix
index e239fafe8..25c402e3a 100644
--- a/modules/roles/warp-client.nix
+++ b/modules/roles/warp-client.nix
@@ -8,7 +8,7 @@
   # Docs:
   # - WARP on Linux: https://developers.cloudflare.com/warp-client/get-started/linux/
   # - Firewall ports: https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/deployment/firewall/
-  flake.nixosModules.warp-client = _: {
+  flake.nixosModules.roles."warp-client" = _: {
     services.cloudflare-warp = {
       enable = true;
       openFirewall = true; # opens UDP 2408

From 14f68ec06c509510b2f6e9fa1a2990cdf6156db4 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Sun, 19 Oct 2025 18:11:32 +0300
Subject: [PATCH 04/20] docs: add Nix debug manual

---
 docs/nix-debugging-manual.md | 109 +++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 docs/nix-debugging-manual.md

diff --git a/docs/nix-debugging-manual.md b/docs/nix-debugging-manual.md
new file mode 100644
index 000000000..5755850e6
--- /dev/null
+++ b/docs/nix-debugging-manual.md
@@ -0,0 +1,109 @@
+# Nix Ecosystem Debugging Manual
+
+## 1. Introduction
+Debugging in the Nix ecosystem spans expression evaluation, reproducible builds, and declarative user environments. This manual summarizes practical techniques drawn from official manuals, community knowledge, and established tooling so you can triage issues systematically across Nix, NixOS, and Home Manager.citeturn15search0
+
+---
+
+## 2. Debugging Nix Language Expressions
+
+### 2.1 Using the Nix REPL (`nix repl`)
+- Launch `nix repl` with flake or file inputs and inspect bindings via `:?`, `:doc`, and `:type` for quick reference while iterating on expressions.citeturn6search1
+- Toggle stack traces interactively with `:show-trace` or collect build logs with `:log <derivation>` to pinpoint failing derivations without leaving the REPL.citeturn6search1
+- Use `:b drv` or `:bl` to build derivations in place, creating GC roots that preserve artifacts for deeper inspection.citeturn6search1
+- Combine `--expr` or `--file` with `--extra-experimental-features 'flakes repl-flake'` when testing flake-based inputs so the REPL mirrors production evaluation settings.citeturn6search1
+
+```bash
+nix repl --expr 'import <nixpkgs> {}'
+nix-repl> :doc builtins.map
+nix-repl> :show-trace
+```
+
+### 2.2 Tracing Evaluation (`builtins.trace`)
+- `builtins.trace "message" value` emits diagnostics while returning `value`, and `builtins.traceVerbose` obeys the `trace-verbose` setting to silence noisy traces in normal runs.citeturn16search2
+- Enable `builtins.break` with `--debugger` and `:bt`/`:st` commands to step through evaluation paths when the standard trace output is insufficient.citeturn16search2
+- Prefer library helpers such as `lib.debug.traceVal`, `traceValFn`, and `traceSeq` to force deeper evaluation or format values without rewriting existing expressions.citeturn15search0
+- For performance investigations, set `trace-function-calls = true` in `nix.conf` to emit function timings, or `trace-import-from-derivation = true` to spot unintentional IFD usage during evaluation.citeturn16search3turn16search4
+
+```nix
+{ lib, ... }:
+
+let
+  traced = lib.debug.traceValFn (v: "expanding ${v}") (builtins.trace "enter" 42);
+in traced
+```
+
+### 2.3 Common Errors and Pitfalls
+- Infinite recursion typically arises when option definitions depend on themselves; convert conditionals into `lib.mkIf` or restructure module arguments to break cycles.citeturn1search0
+- Missing attributes and type mismatches surface clearer diagnostics when rerun with `--show-trace`, which expands stack frames to the originating file and option definition.citeturn16search2
+- Avoid accessing `pkgs.lib` inside module arguments—import `lib` explicitly to prevent recursion through package set initialization.citeturn1search0
+
+### 2.4 Language-Level Debugging Tools (e.g., `nix-debug`, `nix-tree`)
+- Use `nix eval --show-trace --expr '<expr>'` or `nix-instantiate --eval --strict` to surface evaluation errors without building derivations.citeturn6search2
+- Explore dependency graphs with `nix-tree <installable>` or `nix path-info --recursive --closure-size` to identify unexpectedly large closures and hidden references.citeturn19view0turn7search0
+- Compare two derivations using `nix store diff-closures /path/or/flake1 /path/or/flake2` to detect runtime-impacting differences between generations.citeturn7search2
+- Analyze why a package depends on another via `nix why-depends` to trace a single chain of references through the store.citeturn7search1
+- For ad hoc profiling, combine `nix build --keep-failed` with standard Unix tools inside the retained build directory, then refresh caches using `nix log` to review build output.citeturn6search0
+
+---
+
+## 3. Debugging NixOS Systems
+
+### 3.1 Analyzing Build Failures
+- When `nixos-rebuild` aborts, inspect failures immediately with `nix log <installable>`; add `--print-build-logs` or `-L` to stream logs during the rebuild.citeturn6search0
+- Preserve failed build environments with `nix build --keep-failed` or `nix-build --keep-failed` so you can drop into `result-tmp` directories for manual investigation.citeturn6search0
+- Detect nondeterministic outputs by pairing `--check` with `nix store diff-closures` or the `.check` outputs generated after a mismatch.citeturn7search2
+- Use `nix build --keep-going` during large upgrades to aggregate all failing derivations instead of halting at the first error.citeturn6search0
+
+### 3.2 Debugging Systemd Services
+- Query unit health with `systemctl status <unit>` and follow live logs via `journalctl -fu <unit>` or boot-scoped summaries with `journalctl -b`.citeturn2search0
+- On configuration switches, enable verbose activation by exporting `STC_DEBUG=1` before running `sudo nixos-rebuild switch` to view each action performed by `switch-to-configuration`.citeturn2search0
+- For crash loops, combine `systemctl reset-failed <unit>` with targeted restarts so journal output reflects a single activation attempt without historic noise.citeturn2search0
+- Use `nixos-option services.<name>.<option>` to verify the rendered option tree matches expectations before restarting daemons.citeturn4search1
+
+### 3.3 NixOS Debugging Options
+- Apply boot-time flags such as `boot.shell_on_fail`, `boot.trace`, or `systemd.log_level=debug` from the GRUB editor to access emergency shells and high-verbosity journals when early boot fails.citeturn4search2
+- Enable the NixOS test driver’s SSH backdoor or interactive mode when reproducing flaky module tests to inspect the virtual machine state directly.citeturn4search2
+- Configure kernel builds with debug symbols (e.g., `linuxKernel.kernels.<version>.extraConfig = "KGDB y";`) to attach kernel debuggers in low-level investigations.citeturn4search2
+
+### 3.4 Inspecting the Nix Store and Derivations
+- Use `nix path-info --recursive --closure-size /run/current-system` to quantify deployed closure size and locate unexpectedly large dependencies.citeturn7search0
+- Trace dependency chains with `nix why-depends <a> <b>` to justify closures or detect hidden references.citeturn7search1
+- Verify binary provenance by reading store logs (`nix log <installable>`) or listing remote cache metadata with `nix store ls --store https://cache.nixos.org --long <path>`.citeturn6search0turn6search6
+
+---
+
+## 4. Debugging Home Manager
+
+### 4.1 Activation Issues
+- Run `home-manager switch --show-trace` to expand evaluation backtraces for option type or dependency errors before activation aborts.citeturn10view0
+- Inspect the systemd user unit with `systemctl --user status home-manager-$USER.service` and stream logs via `journalctl --user -fu home-manager-$USER.service` on NixOS installations that manage activation as a service.citeturn10view0
+- Use `home-manager switch --dry-run` (or `--activation-trace`) to preview file links without touching the live home directory, then rerun with `--show-trace` if validation fails.citeturn10view0
+
+```bash
+home-manager switch --show-trace
+systemctl --user status "home-manager-$USER.service"
+journalctl --user -fu "home-manager-$USER.service"
+```
+
+### 4.2 Inspecting Generated Files
+- Build without activating using `home-manager build` and inspect the `result` symlink for rendered dotfiles under `result/home-files` or scripts via `result/activate`.citeturn10view0
+- Diff generations with `home-manager generations` followed by `nix store diff-closures $oldGen $newGen` to understand configuration drift before promoting an update.citeturn10view0turn7search2
+- When conflicts arise (e.g., existing files), the activation check lists blocking paths; resolve by moving or adopting them into `home.file.*.source`.citeturn10view0
+
+### 4.3 Debugging Modules
+- Refer to `man home-configuration.nix` or `home-manager help option <name>` to confirm option types, defaults, and merged definitions prior to editing module code.citeturn8search5
+- Custom activation scripts defined under `home.activation.*` should respect `DRY_RUN` and can emit verbose output by checking the `VERBOSE` environment variable set during activation.citeturn11view0
+- Use `home-manager --override-input` or `--flake` overrides to test module patches against alternate Home Manager revisions without disturbing the system profile.citeturn10view0
+
+---
+
+## 5. Useful Third-Party Debugging Tools
+- `nix-tree`: curses UI for exploring dependency trees, ideal for spotting unexpected runtime references.citeturn19view0
+- `nh`: wrapper around common `nixos-rebuild` and `nix` invocations that surfaces switch failures and generation history with readable output.citeturn18search2
+- `nvd`: compare Nix store closures or generations to highlight file-level differences after rebuilds, helping confirm whether a change affects runtime artifacts.citeturn18search2
+
+---
+
+## 6. Conclusion
+By combining REPL-driven diagnostics, structured logging, and store-level introspection, you can shorten feedback loops across Nix expressions, NixOS hosts, and Home Manager environments. Build a personal toolkit from the commands and utilities above, automate recurring checks (e.g., `nix log`, `nix store diff-closures`), and lean on verbose activation modes to keep declarative configurations reliable.citeturn15search0

From a5b786a74f665a8103c23a89a29cb8cd598b5c23 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Sun, 19 Oct 2025 18:26:05 +0300
Subject: [PATCH 05/20] fix(roles): dedupe i3 session module

---
 docs/nix-debugging-manual.md       | 210 ++++++++++++++++++-----------
 modules/meta/nixos-app-helpers.nix |  14 +-
 modules/roles/desktop.nix          |  52 +++++--
 modules/roles/xserver.nix          |  28 +---
 modules/system76/imports.nix       |   4 +-
 modules/system76/usbguard.nix      |   6 +-
 6 files changed, 180 insertions(+), 134 deletions(-)

diff --git a/docs/nix-debugging-manual.md b/docs/nix-debugging-manual.md
index 5755850e6..0cb5524c4 100644
--- a/docs/nix-debugging-manual.md
+++ b/docs/nix-debugging-manual.md
@@ -1,109 +1,159 @@
 # Nix Ecosystem Debugging Manual
 
-## 1. Introduction
-Debugging in the Nix ecosystem spans expression evaluation, reproducible builds, and declarative user environments. This manual summarizes practical techniques drawn from official manuals, community knowledge, and established tooling so you can triage issues systematically across Nix, NixOS, and Home Manager.citeturn15search0
+## 1. Foundational Debugging Principles
 
----
+Effective debugging in the Nix ecosystem requires a conceptual framework that extends beyond mere command execution. Understanding these foundational principles is the bedrock of all advanced techniques.
+
+### 1.1 The Two Phases of Nix: Evaluation vs. Realisation
+
+At the heart of Nix's design is a strict separation between two distinct phases. Identifying which phase an error occurs in is the most critical first step.
+
+- **Evaluation Phase**: A pure, functional process where Nix language code (`.nix` files) is interpreted to produce a set of `.drv` (derivation) files. These files are the blueprints for builds. This phase is where you encounter language-level problems: syntax errors, undefined variables, type mismatches, or infinite recursion.
+- **Realisation (Build) Phase**: An imperative, side-effectful process where the Nix daemon executes a derivation's build script in a sandboxed environment. This is where compilation failures, failed tests, or incorrect file permissions manifest.
+
+An evaluation error (e.g., "undefined variable 'pkgs'") must be diagnosed with language tools like the REPL, not by inspecting build logs, because a build never started. Conversely, a build error (e.g., a C++ compilation failure) must be diagnosed by examining logs (`nix log`) or entering the build environment (`nix-shell`).
+
+### 1.2 Embracing Laziness: Strategies for Forcing Evaluation
+
+Nix is a lazy language, meaning expressions are not evaluated until their results are actually required. This is a frequent source of confusion, as `builtins.trace` statements may not print if the value they are attached to is not used.
+
+To effectively debug, you must force evaluation:
+
+- **In the REPL**: Use the `:p <expression>` command to recursively "print" and fully evaluate a data structure, revealing its complete contents.
+- **In Code**: Use `builtins.deepSeq` or the more robust `lib.debug.traceSeq`. `lib.debug.traceSeq traceVal returnVal` forces the complete, recursive evaluation of `traceVal` before printing it, guaranteeing that you see the full data structure, not a set of unevaluated "thunks."
+
+### 1.3 Controlling Verbosity: Essential Command-Line Flags
+
+- `--show-trace`: **For evaluation errors.** Disables stack trace truncation, revealing the full sequence of function calls and file locations that led to the error. **Always use this for language-level debugging.**
+- `--print-build-logs` / `-L`: **For realisation errors.** Streams the full, real-time build log to the terminal. Essential for diagnosing compilation failures.
+- `--verbose` / `-v`: Increases the verbosity of the Nix tool itself. Can be repeated (e.g., `-vvv`).
 
 ## 2. Debugging Nix Language Expressions
 
-### 2.1 Using the Nix REPL (`nix repl`)
-- Launch `nix repl` with flake or file inputs and inspect bindings via `:?`, `:doc`, and `:type` for quick reference while iterating on expressions.citeturn6search1
-- Toggle stack traces interactively with `:show-trace` or collect build logs with `:log <derivation>` to pinpoint failing derivations without leaving the REPL.citeturn6search1
-- Use `:b drv` or `:bl` to build derivations in place, creating GC roots that preserve artifacts for deeper inspection.citeturn6search1
-- Combine `--expr` or `--file` with `--extra-experimental-features 'flakes repl-flake'` when testing flake-based inputs so the REPL mirrors production evaluation settings.citeturn6search1
+### 2.1 The Interactive Inspector: Mastering the `nix repl`
 
-```bash
-nix repl --expr 'import <nixpkgs> {}'
-nix-repl> :doc builtins.map
-nix-repl> :show-trace
-```
+The Nix REPL is the cornerstone of interactive language debugging.
 
-### 2.2 Tracing Evaluation (`builtins.trace`)
-- `builtins.trace "message" value` emits diagnostics while returning `value`, and `builtins.traceVerbose` obeys the `trace-verbose` setting to silence noisy traces in normal runs.citeturn16search2
-- Enable `builtins.break` with `--debugger` and `:bt`/`:st` commands to step through evaluation paths when the standard trace output is insufficient.citeturn16search2
-- Prefer library helpers such as `lib.debug.traceVal`, `traceValFn`, and `traceSeq` to force deeper evaluation or format values without rewriting existing expressions.citeturn15search0
-- For performance investigations, set `trace-function-calls = true` in `nix.conf` to emit function timings, or `trace-import-from-derivation = true` to spot unintentional IFD usage during evaluation.citeturn16search3turn16search4
+- **Loading Code**: Start with `nix repl` and load files with `:l <path>` or flakes with `:lf .`.
+- **Essential Commands**:
+     - `:p <expr>`: Strictly (deeply) evaluate and print an expression.
+     - `:b <expr>`: Build the derivation the expression evaluates to.
+     - `:log <expr>`: After a build, display its logs.
+     - `:e <expr>`: Open the source code for the expression (e.g., a package) in your `$EDITOR`.
+     - `:show-trace`: Toggle stack traces on/off within the REPL session.
 
-```nix
-{ lib, ... }:
+### 2.2 Print-Style Debugging and Breakpoints
 
-let
-  traced = lib.debug.traceValFn (v: "expanding ${v}") (builtins.trace "enter" 42);
-in traced
-```
+- **`builtins.trace "msg" val`**: The basic tool. Prints `msg` and returns `val`. Subject to lazy evaluation.
+- **`lib.debug.traceSeq val ret`**: The robust tool. Deeply evaluates and prints `val`, then returns `ret`. Use this to avoid laziness issues with complex data structures.
+- **`builtins.break`**: For true interactive debugging. Place `builtins.break val` in your code. When you run a Nix command with the `--debugger` flag, evaluation will pause at that point and drop you into a REPL scoped to that exact location, allowing you to inspect all local variables.
 
 ### 2.3 Common Errors and Pitfalls
-- Infinite recursion typically arises when option definitions depend on themselves; convert conditionals into `lib.mkIf` or restructure module arguments to break cycles.citeturn1search0
-- Missing attributes and type mismatches surface clearer diagnostics when rerun with `--show-trace`, which expands stack frames to the originating file and option definition.citeturn16search2
-- Avoid accessing `pkgs.lib` inside module arguments—import `lib` explicitly to prevent recursion through package set initialization.citeturn1search0
 
-### 2.4 Language-Level Debugging Tools (e.g., `nix-debug`, `nix-tree`)
-- Use `nix eval --show-trace --expr '<expr>'` or `nix-instantiate --eval --strict` to surface evaluation errors without building derivations.citeturn6search2
-- Explore dependency graphs with `nix-tree <installable>` or `nix path-info --recursive --closure-size` to identify unexpectedly large closures and hidden references.citeturn19view0turn7search0
-- Compare two derivations using `nix store diff-closures /path/or/flake1 /path/or/flake2` to detect runtime-impacting differences between generations.citeturn7search2
-- Analyze why a package depends on another via `nix why-depends` to trace a single chain of references through the store.citeturn7search1
-- For ad hoc profiling, combine `nix build --keep-failed` with standard Unix tools inside the retained build directory, then refresh caches using `nix log` to review build output.citeturn6search0
+- **"attribute ‘…’ missing"**: A wrong attrpath or scope. Use the REPL and `builtins.attrNames` to inspect available attributes.
+- **"infinite recursion encountered"**: A circular dependency in a `let` block or `rec` set. Use `trace` to follow the chain of dependencies and find the loop.
 
----
+## 3. Analyzing Derivation Builds
 
-## 3. Debugging NixOS Systems
+When evaluation succeeds but the build fails, shift focus to the realisation phase.
 
-### 3.1 Analyzing Build Failures
-- When `nixos-rebuild` aborts, inspect failures immediately with `nix log <installable>`; add `--print-build-logs` or `-L` to stream logs during the rebuild.citeturn6search0
-- Preserve failed build environments with `nix build --keep-failed` or `nix-build --keep-failed` so you can drop into `result-tmp` directories for manual investigation.citeturn6search0
-- Detect nondeterministic outputs by pairing `--check` with `nix store diff-closures` or the `.check` outputs generated after a mismatch.citeturn7search2
-- Use `nix build --keep-going` during large upgrades to aggregate all failing derivations instead of halting at the first error.citeturn6search0
+### 3.1 Post-Mortem Analysis: Reading Build Logs
 
-### 3.2 Debugging Systemd Services
-- Query unit health with `systemctl status <unit>` and follow live logs via `journalctl -fu <unit>` or boot-scoped summaries with `journalctl -b`.citeturn2search0
-- On configuration switches, enable verbose activation by exporting `STC_DEBUG=1` before running `sudo nixos-rebuild switch` to view each action performed by `switch-to-configuration`.citeturn2search0
-- For crash loops, combine `systemctl reset-failed <unit>` with targeted restarts so journal output reflects a single activation attempt without historic noise.citeturn2search0
-- Use `nixos-option services.<name>.<option>` to verify the rendered option tree matches expectations before restarting daemons.citeturn4search1
+- **`nix log <derivation-path.drv>`**: The canonical command to retrieve the complete, unabridged log of a failed build attempt. The path to the failed `.drv` is always in the error message.
+- **Preserving Failed Builds**: Use `nix build --keep-failed`. This preserves the temporary build directory (e.g., in `/tmp/`) so you can `cd` into it for manual investigation.
+- **Aggregating Failures**: Use `nix build --keep-going` during large builds to see all failing derivations instead of halting at the first error.
 
-### 3.3 NixOS Debugging Options
-- Apply boot-time flags such as `boot.shell_on_fail`, `boot.trace`, or `systemd.log_level=debug` from the GRUB editor to access emergency shells and high-verbosity journals when early boot fails.citeturn4search2
-- Enable the NixOS test driver’s SSH backdoor or interactive mode when reproducing flaky module tests to inspect the virtual machine state directly.citeturn4search2
-- Configure kernel builds with debug symbols (e.g., `linuxKernel.kernels.<version>.extraConfig = "KGDB y";`) to attach kernel debuggers in low-level investigations.citeturn4search2
+### 3.2 Interactive Build Debugging with `nix-shell`
 
-### 3.4 Inspecting the Nix Store and Derivations
-- Use `nix path-info --recursive --closure-size /run/current-system` to quantify deployed closure size and locate unexpectedly large dependencies.citeturn7search0
-- Trace dependency chains with `nix why-depends <a> <b>` to justify closures or detect hidden references.citeturn7search1
-- Verify binary provenance by reading store logs (`nix log <installable>`) or listing remote cache metadata with `nix store ls --store https://cache.nixos.org --long <path>`.citeturn6search0turn6search6
+This is the most powerful technique for complex build failures.
 
----
+1. Instead of `nix build`, run `nix-shell <derivation.nix>`. This drops you into an interactive shell with the _exact_ same environment as the builder.
+2. All environment variables (`$src`, `$out`, `NIX_CFLAGS_COMPILE`, etc.) are set.
+3. The standard build phases are available as shell functions. You can run them manually and in order: `unpackPhase`, `configurePhase`, `buildPhase`, `installPhase`.
+4. Inspect the logic of a phase with `type buildPhase`.
+5. If a phase fails, you can modify its logic by copying its definition, editing it, and pasting the new version directly into your shell. Rerunning the phase will execute your modified version, allowing for rapid iteration.
 
-## 4. Debugging Home Manager
+### 3.3 Advanced Hooks: Pausing Failed Builds with `breakpointHook`
 
-### 4.1 Activation Issues
-- Run `home-manager switch --show-trace` to expand evaluation backtraces for option type or dependency errors before activation aborts.citeturn10view0
-- Inspect the systemd user unit with `systemctl --user status home-manager-$USER.service` and stream logs via `journalctl --user -fu home-manager-$USER.service` on NixOS installations that manage activation as a service.citeturn10view0
-- Use `home-manager switch --dry-run` (or `--activation-trace`) to preview file links without touching the live home directory, then rerun with `--show-trace` if validation fails.citeturn10view0
+For non-deterministic or CI build failures, add `pkgs.breakpointHook` to the `nativeBuildInputs` of a derivation. If the build fails, the hook will freeze the build environment and print a `cntr attach` command. Running this command as root will attach you to the namespaces of the failed build process for post-mortem analysis.
 
-```bash
-home-manager switch --show-trace
-systemctl --user status "home-manager-$USER.service"
-journalctl --user -fu "home-manager-$USER.service"
-```
+## 4. Troubleshooting NixOS Systems
 
-### 4.2 Inspecting Generated Files
-- Build without activating using `home-manager build` and inspect the `result` symlink for rendered dotfiles under `result/home-files` or scripts via `result/activate`.citeturn10view0
-- Diff generations with `home-manager generations` followed by `nix store diff-closures $oldGen $newGen` to understand configuration drift before promoting an update.citeturn10view0turn7search2
-- When conflicts arise (e.g., existing files), the activation check lists blocking paths; resolve by moving or adopting them into `home.file.*.source`.citeturn10view0
+### 4.1 Diagnosing `nixos-rebuild` Failures
 
-### 4.3 Debugging Modules
-- Refer to `man home-configuration.nix` or `home-manager help option <name>` to confirm option types, defaults, and merged definitions prior to editing module code.citeturn8search5
-- Custom activation scripts defined under `home.activation.*` should respect `DRY_RUN` and can emit verbose output by checking the `VERBOSE` environment variable set during activation.citeturn11view0
-- Use `home-manager --override-input` or `--flake` overrides to test module patches against alternate Home Manager revisions without disturbing the system profile.citeturn10view0
+- **Verbose Activation**: For activation-phase issues, get a detailed trace of the `switch-to-configuration` script's actions by running: `export STC_DEBUG=1; sudo nixos-rebuild switch`
+- **Generation Differences**: To understand what changed between the current system and the one you are trying to build, use `nix store diff-closures /run/current-system ./result`.
 
----
+### 4.2 Debugging Systemd Services
 
-## 5. Useful Third-Party Debugging Tools
-- `nix-tree`: curses UI for exploring dependency trees, ideal for spotting unexpected runtime references.citeturn19view0
-- `nh`: wrapper around common `nixos-rebuild` and `nix` invocations that surfaces switch failures and generation history with readable output.citeturn18search2
-- `nvd`: compare Nix store closures or generations to highlight file-level differences after rebuilds, helping confirm whether a change affects runtime artifacts.citeturn18search2
+- **`systemctl status <unit>`**: First command to check a service's state and recent logs.
+- **`journalctl -u <unit>`**: View the complete log history for a service.
+- **`journalctl -f`**: Follow logs in real-time.
+- **`systemctl cat <unit>`**: See the exact unit file NixOS generated.
+- **`systemd-analyze blame` / `critical-chain`**: Find slow or hung services during boot.
 
----
+### 4.3 Investigating Boot and Kernel Issues
 
-## 6. Conclusion
-By combining REPL-driven diagnostics, structured logging, and store-level introspection, you can shorten feedback loops across Nix expressions, NixOS hosts, and Home Manager environments. Build a personal toolkit from the commands and utilities above, automate recurring checks (e.g., `nix log`, `nix store diff-closures`), and lean on verbose activation modes to keep declarative configurations reliable.citeturn15search0
+The NixOS boot process has two stages. Debugging Stage 1 (the initrd) requires special kernel parameters, added at the boot menu:
+
+- **`rd.systemd.debug_shell`**: Spawns a debug shell on TTY9 (Ctrl+Alt+F9) inside the initrd environment, allowing you to debug issues like LUKS decryption or ZFS pool imports.
+- **`boot.shell_on_fail`**: Drops to a root shell on stage-1 failure.
+- **`boot.trace`**: Enables `set -x` tracing for all stage-1/2 scripts.
+
+### 4.4 Managing Debug Symbols
+
+By default, Nix packages are stripped. To debug with GDB:
+
+- **Per-Package**: Use `pkgs.enableDebugging <package>` to recompile a single package with full debug info.
+- **System-Wide**: Set `environment.enableDebugInfo = true;` in `configuration.nix`.
+- **On-Demand (Recommended)**: Use a debuginfod server like `nixseparatedebuginfod`. This allows GDB to automatically download required debug symbols and source files over HTTP as they are needed.
+
+## 5. Debugging Home Manager
+
+### 5.1 Diagnosing Activation and Service Failures
+
+- **Dry Run**: Preview the changes that will be made without touching your home directory: `home-manager switch --dry-run`.
+- **Check the Service**: Home Manager uses a user-level systemd instance. Check for activation errors with `journalctl --user -u home-manager-$USER.service`.
+- **Custom Activation Scripts**: If you write custom `home.activation` scripts, note that they are passed `DRY_RUN` and `VERBOSE` environment variables, which your scripts should respect.
+
+### 5.2 Inspecting and Iterating on Generated Files
+
+To iterate quickly on a configuration (e.g., for `nvim`), use `config.lib.file.mkOutOfStoreSymlink` to create a symlink that points directly to the source file in your configuration directory. This allows changes to be reflected immediately without needing to run `home-manager switch` until you are done.
+
+## 6. Useful Third-Party Debugging Tools
+
+- **`nix-tree`**: Interactive TUI to browse dependency graphs.
+- **`nvd`**: Diffs the contents of two closures to see what files changed.
+- **`manix`**: CLI doc/option search across nixpkgs, NixOS, and Home Manager.
+- **`nh`**: Ergonomic wrapper for `nixos-rebuild` and `home-manager`.
+
+## 7. Quick Reference
+
+```bash
+# --- Language & Evaluation ---
+nix repl               # Start REPL, then :? :l :lf :p :b
+nix build . --show-trace # Get full error trace on evaluation failure
+
+# --- Build Failures ---
+nixos-rebuild switch -L # Stream build logs
+nix log /nix/store/<hash>.drv # View logs of a failed build
+nix-shell <derivation>   # Enter interactive build shell
+nix build --keep-failed  # Preserve failed build directory for inspection
+
+# --- Dependency & Generation Analysis ---
+nix why-depends <a> <b> # Explain dependency path
+nix store diff-closures <gen1> <gen2> # Show differences between generations
+
+# --- NixOS System ---
+systemctl status <unit>
+journalctl -u <unit> -b -1 # Logs from previous boot
+export STC_DEBUG=1; sudo nixos-rebuild switch # Verbose activation
+
+# --- Boot Flags (add at boot menu) ---
+rd.systemd.debug_shell boot.shell_on_fail boot.trace
+
+# --- Home Manager ---
+home-manager switch --dry-run # Preview changes
+home-manager switch --show-trace -L -v # Verbose build/activation
+journalctl --user -fu home-manager-$USER.service
+```
diff --git a/modules/meta/nixos-app-helpers.nix b/modules/meta/nixos-app-helpers.nix
index 1fb27eb7c..dfdf90135 100644
--- a/modules/meta/nixos-app-helpers.nix
+++ b/modules/meta/nixos-app-helpers.nix
@@ -88,10 +88,7 @@ let
           ]
         else
           throw (
-            "nixos-app-helpers: expected "
-            + toString filePath
-            + " to export flake.nixosModules.apps."
-            + appName
+            "nixos-app-helpers: expected " + toString filePath + " to export flake.nixosModules.apps." + appName
           )
     else
       acc
@@ -125,14 +122,9 @@ let
               if lib.hasAttrByPath path imported then
                 lib.getAttrFromPath path imported
               else
-                throw (
-                  "nixos-app-helpers: app module missing path "
-                  + builtins.concatStringsSep "." path
-                )
+                throw ("nixos-app-helpers: app module missing path " + builtins.concatStringsSep "." path)
             else
-              throw (
-                "nixos-app-helpers: missing app file " + toString maybeFile
-              );
+              throw ("nixos-app-helpers: missing app file " + toString maybeFile);
           previewList = lib.take 20 appKeys;
           preview = lib.concatStringsSep ", " previewList;
           ellipsis = if lib.length appKeys > 20 then ", …" else "";
diff --git a/modules/roles/desktop.nix b/modules/roles/desktop.nix
index c8e60ae2c..32c88b24b 100644
--- a/modules/roles/desktop.nix
+++ b/modules/roles/desktop.nix
@@ -11,18 +11,44 @@ let
   getApp = rawHelpers.getApp or fallbackGetApp;
   getApps = rawHelpers.getApps or (names: map getApp names);
 
-  xserverRolePath = [ "roles" "xserver" ];
-  xserverRole =
-    if lib.hasAttrByPath xserverRolePath config.flake.nixosModules then
-      lib.getAttrFromPath xserverRolePath config.flake.nixosModules
+  roleHelpers = config._module.args.nixosRoleHelpers or { };
+  rawRoleHelpers = (config.flake.lib.nixos.roles or { }) // roleHelpers;
+  fallbackGetRole =
+    name:
+    let
+      filePath = ../roles + "/${name}.nix";
+      imported = if builtins.pathExists filePath then import filePath else null;
+      modulePath = [
+        "flake"
+        "nixosModules"
+        "roles"
+        name
+      ];
+    in
+    if imported != null && lib.hasAttrByPath modulePath imported then
+      lib.getAttrFromPath modulePath imported
     else
-      throw "Desktop role requires flake.nixosModules.roles.xserver";
-  i3ModulePath = [ "window-manager" "i3" ];
-  i3Module =
-    if lib.hasAttrByPath i3ModulePath config.flake.nixosModules then
-      lib.getAttrFromPath i3ModulePath config.flake.nixosModules
+      throw ("Desktop role requires flake.nixosModules.roles." + name);
+  getRole = rawRoleHelpers.getRole or fallbackGetRole;
+  xserverRole = getRole "xserver";
+
+  getWindowManagerModule =
+    name:
+    let
+      filePath = ../window-manager + "/${name}.nix";
+      imported = if builtins.pathExists filePath then import filePath else null;
+      modulePath = [
+        "flake"
+        "nixosModules"
+        "window-manager"
+        name
+      ];
+    in
+    if imported != null && lib.hasAttrByPath modulePath imported then
+      lib.getAttrFromPath modulePath imported
     else
-      throw "Desktop role requires flake.nixosModules.window-manager.i3";
+      throw ("Desktop role requires flake.nixosModules.window-manager." + name);
+  i3Module = getWindowManagerModule "i3";
 
   desktopApps = [
     "blueberry"
@@ -39,7 +65,11 @@ let
     "udiskie"
   ];
 
-  roleImports = [ xserverRole i3Module ] ++ getApps desktopApps;
+  roleImports = [
+    xserverRole
+    i3Module
+  ]
+  ++ getApps desktopApps;
 in
 {
   flake.nixosModules.roles.desktop.imports = roleImports;
diff --git a/modules/roles/xserver.nix b/modules/roles/xserver.nix
index ad5eecc64..f79e49298 100644
--- a/modules/roles/xserver.nix
+++ b/modules/roles/xserver.nix
@@ -21,30 +21,8 @@ let
         lib.getAttrFromPath modulePath imported
       else
         throw ("Unknown NixOS app '" + name + "' (role xserver)");
-  getApp =
-    name:
-    if rawHelpers ? getApp then rawHelpers.getApp name else fallbackGetApp name;
-  getApps =
-    names:
-    if rawHelpers ? getApps then rawHelpers.getApps names else map getApp names;
-  i3SessionModule =
-    { pkgs, lib, ... }:
-    {
-      services = {
-        xserver = {
-          enable = lib.mkDefault true;
-          windowManager.i3 = {
-            enable = true;
-            package = pkgs.i3-gaps;
-          };
-          displayManager.lightdm.enable = true;
-        };
-
-        displayManager.defaultSession = lib.mkDefault "none+i3";
-
-        "systemd-lock-handler".enable = lib.mkDefault true;
-      };
-    };
+  getApp = name: if rawHelpers ? getApp then rawHelpers.getApp name else fallbackGetApp name;
+  getApps = names: if rawHelpers ? getApps then rawHelpers.getApps names else map getApp names;
   xserverApps = [
     "arandr"
     "autotiling-rs"
@@ -64,7 +42,7 @@ let
     "xclip"
     "xkill"
   ];
-  roleImports = [ i3SessionModule ] ++ getApps xserverApps;
+  roleImports = getApps xserverApps;
 in
 {
   flake.nixosModules.roles.xserver.imports = roleImports;
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index 915463cb4..e52d8cd26 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -23,9 +23,7 @@ let
       lib.getAttrFromPath [ "roles" name ] nixosModules
     else
       throw (
-        "system76 host requires role "
-        + name
-        + " but it was not found in helpers or flake.nixosModules"
+        "system76 host requires role " + name + " but it was not found in helpers or flake.nixosModules"
       );
   roleModules = map getRoleModule roleNames;
   getVirtualizationModule =
diff --git a/modules/system76/usbguard.nix b/modules/system76/usbguard.nix
index ac2ada7f5..b561df270 100644
--- a/modules/system76/usbguard.nix
+++ b/modules/system76/usbguard.nix
@@ -11,10 +11,8 @@ let
       flakeLib = libAttrs.flake or { };
       securityLib = (flakeLib.lib or { }).security or { };
     in
-    if securityLib ? usbguard then
-      securityLib.usbguard
-    else
-      throw "system76/usbguard: securityLib.usbguard missing; ensure usbguard-lib exports the helper";
+    securityLib.usbguard
+      or (throw "system76/usbguard: securityLib.usbguard missing; ensure usbguard-lib exports the helper");
   baseRulesRaw = usbguardLib.baseRules or null;
   baseRules =
     if baseRulesRaw == null || lib.strings.trim baseRulesRaw == "" then

From aa9fa5b2a0f7921a02243f068112f903ff543f99 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Sun, 19 Oct 2025 19:50:03 +0300
Subject: [PATCH 06/20] chore: fix formatting

---
 docs/nix-debugging-manual.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/nix-debugging-manual.md b/docs/nix-debugging-manual.md
index 0cb5524c4..57f47749d 100644
--- a/docs/nix-debugging-manual.md
+++ b/docs/nix-debugging-manual.md
@@ -36,11 +36,11 @@ The Nix REPL is the cornerstone of interactive language debugging.
 
 - **Loading Code**: Start with `nix repl` and load files with `:l <path>` or flakes with `:lf .`.
 - **Essential Commands**:
-     - `:p <expr>`: Strictly (deeply) evaluate and print an expression.
-     - `:b <expr>`: Build the derivation the expression evaluates to.
-     - `:log <expr>`: After a build, display its logs.
-     - `:e <expr>`: Open the source code for the expression (e.g., a package) in your `$EDITOR`.
-     - `:show-trace`: Toggle stack traces on/off within the REPL session.
+  - `:p <expr>`: Strictly (deeply) evaluate and print an expression.
+  - `:b <expr>`: Build the derivation the expression evaluates to.
+  - `:log <expr>`: After a build, display its logs.
+  - `:e <expr>`: Open the source code for the expression (e.g., a package) in your `$EDITOR`.
+  - `:show-trace`: Toggle stack traces on/off within the REPL session.
 
 ### 2.2 Print-Style Debugging and Breakpoints
 

From bf207ac0b3b16b9a6f4d2bfe72542d2a77b3862d Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 08:31:14 +0300
Subject: [PATCH 07/20] fix: enable ssh

---
 modules/networking/ssh-system.nix | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/modules/networking/ssh-system.nix b/modules/networking/ssh-system.nix
index 96b02ee32..f579b8e97 100644
--- a/modules/networking/ssh-system.nix
+++ b/modules/networking/ssh-system.nix
@@ -1,5 +1,20 @@
+_:
 {
-  # Avoid setting a global IdentityAgent so SSH respects SSH_AUTH_SOCK.
-  # User-level config (Home Manager) sets the stable gpg-agent symlink.
-  flake.nixosModules.base = { };
+  # Keep SSH server available but restrict authentication to keys only and block root logins.
+  # We purposely avoid global IdentityAgent tweaks so SSH continues to honour SSH_AUTH_SOCK;
+  # Home Manager config is responsible for pointing clients at the gpg-agent socket.
+  flake.nixosModules.base =
+    { lib, ... }:
+    {
+      services.openssh = {
+        enable = lib.mkDefault true;
+        openFirewall = lib.mkDefault true;
+        settings = {
+          PasswordAuthentication = false;
+          ChallengeResponseAuthentication = false;
+          KbdInteractiveAuthentication = false;
+          PermitRootLogin = "no";
+        };
+      };
+    };
 }

From 8188b448b69ea76e48236aeb86c284d15d8d33b7 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 08:31:51 +0300
Subject: [PATCH 08/20] fix: remove restting of _module.args

---
 modules/networking/ssh-system.nix | 3 +--
 modules/security/secrets.nix      | 1 -
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/modules/networking/ssh-system.nix b/modules/networking/ssh-system.nix
index f579b8e97..cae450069 100644
--- a/modules/networking/ssh-system.nix
+++ b/modules/networking/ssh-system.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   # Keep SSH server available but restrict authentication to keys only and block root logins.
   # We purposely avoid global IdentityAgent tweaks so SSH continues to honour SSH_AUTH_SOCK;
   # Home Manager config is responsible for pointing clients at the gpg-agent socket.
diff --git a/modules/security/secrets.nix b/modules/security/secrets.nix
index abcae86f5..a76eb0056 100644
--- a/modules/security/secrets.nix
+++ b/modules/security/secrets.nix
@@ -29,7 +29,6 @@
 
         # Only declare secrets if the encrypted file is present in repo
         # (prevents evaluation errors when secrets repo is absent)
-        _module.args = { };
       }
       // lib.mkIf actSecretExists {
         sops.secrets."act/github_token" = {

From 1a93a7108d3c6b8466d44a3555ecd07ce802d28c Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 10:50:40 +0300
Subject: [PATCH 09/20] chore: update docs

---
 docs/home-manager-debug-log.md             | 34 ++++++++++++++++++++++
 docs/system76-home-manager-observations.md | 33 +++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 docs/home-manager-debug-log.md
 create mode 100644 docs/system76-home-manager-observations.md

diff --git a/docs/home-manager-debug-log.md b/docs/home-manager-debug-log.md
new file mode 100644
index 000000000..197ce426d
--- /dev/null
+++ b/docs/home-manager-debug-log.md
@@ -0,0 +1,34 @@
+# Home Manager Config Debug Log
+
+- 2025-10-19 (trace run #1) `nix --accept-flake-config eval .#nixosConfigurations.system76.config."home-manager"`
+  - Output only contained `extraAppImports`.
+  - Confirms regression relative to expected attrset.
+- Added temporary `builtins.trace` in `modules/home-manager/nixos.nix` to verify module execution.
+  - Trace fired, showing `hm-base config (hm input present)`.
+  - Indicates the base module runs and sees the Home Manager input.
+- Evaluated `options.home-manager` with `--show-trace`.
+  - Only option exposed is `home-manager.extraAppImports`.
+  - Suggests upstream Home Manager module is not being imported into the System76 configuration.
+- Inspected module aggregation: `modules/roles/base.nix` imports `flake.nixosModules.base`, and `modules/workstation.nix` adds that role via `baseImport`. Therefore the Home Manager integration _is_ part of the System76 stack; the missing fields stem from a later override rather than the base bundle never loading.
+  - Next step: trace where `config.home-manager` gets replaced after the base merge—likely by a module assigning `home-manager = { extraAppImports = …; }` instead of using `lib.mkMerge`/`mkAfter`.
+- Added a `builtins.trace` wrapper around `config.home-manager` in `modules/home-manager/nixos.nix`; during evaluation it reports the base module assigning keys `backupFileExtension`, `extraSpecialArgs`, `useGlobalPkgs`, and `users`.
+  - Despite that, the final merged `config.home-manager` still renders with only `extraAppImports`, confirming a later definition is overwriting (not merging) the attrset.
+  - Next step: hunt for modules that set `config.home-manager = …` or otherwise replace the attrset (e.g., via `lib.mkForce`) rather than merging nested attributes.
+- Traversed `nixosConfigurations.system76._module.args.modules` and the nested import graph: the upstream Home Manager module is included (wrapped inside the base aggregator), and only the base module contributes keys under `config.home-manager`.
+  - Option introspection shows `home-manager.extraAppImports` receives three definitions, all from the System76 host modules (`modules/system76/imports.nix`, `modules/system76/virtualization.nix`, `modules/system76/home-manager-apps.nix`).
+  - Current hypothesis: one of those host-level modules replaces `config.home-manager` wholesale, leaving only `extraAppImports` in the final view.
+  - Next step: reuse the real `_module.args` with `lib.evalModules` so we can inspect the merged `config.home-manager` after each host module is applied.
+- 2025-10-20 (trace run #2) sanity-check on module wiring.
+  - `rg` sweep shows `modules/home-manager/nixos.nix` is the only place assigning `config.home-manager = { … }`, so the missing attrset is due to the module never being imported rather than a later override.
+  - Confirmed via `modules/system76/imports.nix` that the host expects to pick up `flake.nixosModules.base` indirectly through the workstation bundle; the host layer itself does not import base directly.
+  - Reviewed `modules/workstation.nix`: `baseImport` should resolve the base role and pull in the module that provides the Home Manager glue, but we have not yet verified that the role resolution actually succeeds for System76.
+  - Attempted to print `nixosConfigurations.system76._module.args.modules` (`nix eval --accept-flake-config --impure …`) and only saw `<lambda>`/`<unknown>` placeholders, so we still need better instrumentation (e.g., `lib.debug.traceValSeq`) to confirm whether the base module lands in the import stack.
+  - Next step: instrument workstation assembly (or reuse `_module.args`) to ensure the base role contributes the Home Manager module before continuing with further hypotheses.
+- Instrumented `modules/workstation.nix` with `builtins.trace` to log the resolved module lists; `baseImport` returns a single attrset (the base role), so the workstation bundle _is_ pulling a role wrapper—we still need to verify that role actually imports the Home Manager glue downstream.
+- Added tracing in `modules/roles/base.nix`; the base role resolves to `/flake.nix#nixosModules.base` plus a long list of app modules, so the role itself is constructed correctly.
+- Initially checked `hasHM = builtins.any (m: m._file == ".../modules/home-manager/nixos.nix") flake.outputs.nixosModules.base.imports` and got `false`, but that equality test compared against the working-tree path instead of the store path the aggregator emits, so the result was a false negative.
+- Drilled into `flake.outputs.nixosModules.base` directly: index `30` corresponds to the module synthesized from `modules/home-manager/nixos.nix`. That synthesized module does carry `imports = [ /nix/store/.../nixos ]`, yet when we query `nixosConfigurations.system76.options.home-manager`, the only defined option is still `extraAppImports`. Conclusion: `inputs.home-manager.nixosModules.home-manager` is present in the import graph but apparently not evaluating (or its options are not surfacing), so the next step is to inspect the import-tree glue to understand how it rewrites module contributions and why the upstream Home Manager options/config never make it to the host.
+- Confirmed that the generated module for `modules/home-manager/nixos.nix` still exposes the expected config keys (`backupFileExtension`, `extraSpecialArgs`, `useGlobalPkgs`, `users`) and imports the upstream Home Manager module; however, enumerating `nixosConfigurations.system76.config.home-manager` via `nix eval --json` continues to show only `extraAppImports`, which means something later in the host stack either drops or never merges those keys.
+- Dumped `nixosConfigurations.system76._module.args.modules` to hunt for a later overwrite; the list mainly contains anonymous functions and nothing with a visible `config.home-manager`, suggesting the base Home Manager glue might never reach the host evaluation despite being present in the aggregated `flake.nixosModules.base` imports. Need to trace how the import-tree generated workstation/base modules end up in `_module.args.modules` to confirm whether the glue module is skipped entirely or stripped when converted to callable modules.
+- New finding: `modules/security/secrets.nix` set `_module.args = { };` (no merge helper). Inspecting the evaluated host with `nix eval --accept-flake-config '.#nixosConfigurations.system76._module.args' --apply builtins.attrNames` showed the resulting attrset lacked `inputs`/`self`, so the Home Manager glue fell back to `{}` for `moduleArgs.inputs`. Hypothesis confirmed: secrets module ran after the glue and wiped `_module.args`, stripping helper arguments for everything downstream. **Action:** removed that assignment entirely so helper args flow through. After removal the host still reports only `home-manager.extraAppImports`, which confirms the wipe was part of the problem but not the whole story; next step is to decode how `nixosConfigurations.system76._module.args.modules` expands (currently `[<function>, attrset-with-21 imports, <function>]`) and where the base glue is supposed to be injected so we can reintroduce the Home Manager defaults.
+- Tried re-introducing `(getModule "base")` into `modules/system76/imports.nix` so the host would explicitly import the base bundle. Running `nix flake check --accept-flake-config` failed with `Home Manager base module: expected flake.homeManagerModules.base to be available.` Root cause: pulling the base module directly from the host bypasses the workstation/role pipeline that populates `flake.homeManagerModules.*`; when the base module runs this early, the aggregator hasn’t registered `flake.homeManagerModules.base` yet, so the glue throws. Reverted the change and noted that the base bundle is supposed to arrive via the workstation profile instead.
diff --git a/docs/system76-home-manager-observations.md b/docs/system76-home-manager-observations.md
new file mode 100644
index 000000000..a27248a48
--- /dev/null
+++ b/docs/system76-home-manager-observations.md
@@ -0,0 +1,33 @@
+# System76 Home Manager Integration – Current Findings
+
+## Summary
+
+System76’s NixOS host does import the workstation bundle and the System76‑specific overlays, but the Home Manager glue never succeeds. As a result the evaluated configuration only exposes the `home-manager.extraAppImports` knob, and no Home Manager users or defaults are generated.
+
+## Key Observations
+
+- `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager'` returns an attrset with just `extraAppImports`, confirming the broader Home Manager config never materialises.
+- Querying `config.home-manager.users` via  
+  `nix eval --accept-flake-config --impure --expr 'let flake = builtins.getFlake (toString ./.) ; in flake.nixosConfigurations.system76.config.home-manager.users'`  
+  fails with `attribute 'users' missing`; the owner import from `modules/home-manager/nixos.nix` never ran.
+- The module args visible during host evaluation omit flake inputs:  
+  `nix eval --accept-flake-config '.#nixosConfigurations.system76._module.args' --apply builtins.attrNames`  
+  → `[ "baseModules" "extendModules" "extraModules" "moduleType" "modules" "noUserModules" "pkgs" "utils" ]`.
+- `_module.specialArgs` confirms only the default `modulesPath` is passed through (`nix eval … '_module.specialArgs'`), so no `inputs`/`self` reach downstream modules.
+- `modules/system76/imports.nix` builds `nixosConfigurations.system76` by calling `inputs.nixpkgs.lib.nixosSystem { modules = [ … config.configurations.nixos.system76.module ]; }` without any `specialArgs`. Because of that, the module system never seeds `_module.args.inputs`, and the Home Manager glue’s lookup of `flake.homeManagerModules.base` fails.
+- Inspecting `flake.outputs.nixosModules.base` directly shows the Home Manager glue is already missing **before** the role helper runs: every entry— including `modules/home-manager/nixos.nix`—exposes only `_file` and `imports`, with no `flake.homeManagerModules` or `config.home-manager` payload. This confirms the loss happens upstream of the role sanitisation.
+
+## Consequence
+
+With `_module.args.inputs` empty, `modules/home-manager/nixos.nix` cannot locate the aggregated Home Manager modules. The default user stanza throws, short‑circuiting option registration, leaving only whichever attributes the System76 overlays append (e.g., `extraAppImports`/`sharedModules`).
+
+## Scratch Reproduction
+
+Evaluating the live module list via `lib.evalModules` shows that injecting `specialArgs = { inputs = flake.inputs; self = flake; }` **alone** does not restore the missing options: both the original evaluation and the instrumented rerun still produce a `config.home-manager` attrset with only `extraAppImports`. This means the attrset is being overwritten (or never populated) later in the module chain, not simply blocked by missing `specialArgs`.
+
+A dedicated scaffold (`debug/system76-home-manager-scaffold.nix`) now recreates the System76 import stack with option stubs and per-module traces. The trace output shows every System76 import (including the “pre-system76” checkpoint) observing only `home-manager = { extraAppImports = … }`, so the attrset is already collapsed before any of the System76 overlays execute. The culprit therefore lies in the shared `flake.nixosModules.base` pipeline.
+
+## Next Investigation Steps
+
+1. Extend the scaffold to the base aggregator and pinpoint the exact module under `flake.nixosModules.base` that drops the Home Manager keys.
+2. Once the culprit is identified, decide whether to feed flake inputs there, merge instead of overwrite, or rearrange imports.

From e55b70124f0a01764e4ff575e47d208cdc181844 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 10:59:07 +0300
Subject: [PATCH 10/20] feat: add debug scaffold

---
 debug/system76-home-manager-scaffold.nix | 129 +++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 debug/system76-home-manager-scaffold.nix

diff --git a/debug/system76-home-manager-scaffold.nix b/debug/system76-home-manager-scaffold.nix
new file mode 100644
index 000000000..01e79492d
--- /dev/null
+++ b/debug/system76-home-manager-scaffold.nix
@@ -0,0 +1,129 @@
+{
+  flake ? builtins.getFlake (toString ./.),
+  lib ? flake.inputs.nixpkgs.lib,
+}:
+let
+  baseModules = flake.nixosConfigurations.system76._module.args.modules;
+  specialArgsBase = flake.nixosConfigurations.system76._module.specialArgs;
+  specialArgs = specialArgsBase // {
+    inputs = flake.inputs;
+    self = flake;
+  };
+
+  freeform = lib.types.attrsOf lib.types.anything;
+
+  mkNamespaceOption =
+    name:
+    lib.mkOption {
+      type = lib.types.submodule { freeformType = freeform; };
+      default = { };
+      description = "${name} scaffold (debug only)";
+    };
+
+  scaffoldModule =
+    { lib, ... }:
+    let
+      libStub = flake.lib or { };
+    in
+    {
+      options = {
+        flake = lib.mkOption {
+          type = lib.types.attrs;
+          default = flake;
+        };
+        nixpkgs = lib.mkOption {
+          type = lib.types.submodule { freeformType = freeform; };
+          default = flake.inputs.nixpkgs or { };
+        };
+        system = lib.mkOption {
+          type = lib.types.str;
+          default = "x86_64-linux";
+        };
+        boot = mkNamespaceOption "boot";
+        environment = mkNamespaceOption "environment";
+        services = mkNamespaceOption "services";
+        users = mkNamespaceOption "users";
+        hardware = mkNamespaceOption "hardware";
+        networking = mkNamespaceOption "networking";
+        virtualisation = mkNamespaceOption "virtualisation";
+        lib = lib.mkOption {
+          type = lib.types.attrs;
+          default = libStub;
+        };
+        debug.hmTrace = mkNamespaceOption "debug.hmTrace";
+        assertions = lib.mkOption {
+          type = lib.types.listOf lib.types.anything;
+          default = [ ];
+        };
+        warnings = lib.mkOption {
+          type = lib.types.listOf lib.types.anything;
+          default = [ ];
+        };
+      };
+    };
+
+  mkTraceModule =
+    label:
+    { config, ... }:
+    let
+      hm = config.home-manager or { };
+      names = builtins.attrNames hm;
+      msg = if names == [ ] then "<empty>" else builtins.concatStringsSep ", " names;
+    in
+    {
+      config.debug.hmTrace.${label} = msg;
+    };
+
+  first = builtins.elemAt baseModules 0;
+  top = builtins.elemAt baseModules 1;
+  last = builtins.elemAt baseModules 2;
+
+  imports = top.imports;
+
+  pairs = lib.imap (index: module: {
+    inherit module;
+    label = "system76/" + builtins.toString index;
+  }) imports;
+
+  interleaved = lib.concatMap (pair: [
+    pair.module
+    (mkTraceModule pair.label)
+  ]) pairs;
+
+  modules = [
+    scaffoldModule
+    first
+    (mkTraceModule "pre-system76")
+    (top // { imports = interleaved; })
+    last
+  ];
+
+  baseTop = flake.nixosModules.base;
+  baseImports = baseTop.imports;
+
+  basePairs = lib.imap (index: module: {
+    inherit module;
+    label = "base/" + builtins.toString index;
+  }) baseImports;
+
+  baseInterleaved = lib.concatMap (pair: [
+    pair.module
+    (mkTraceModule pair.label)
+  ]) basePairs;
+
+  baseModule = baseTop // {
+    imports = baseInterleaved;
+  };
+  baseModulesForTrace = [
+    scaffoldModule
+    baseModule
+  ];
+in
+{
+  inherit
+    modules
+    specialArgs
+    baseModule
+    baseModulesForTrace
+    ;
+}

From 187cbe4d82cd2746086d5a29ca50095715a885fe Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 12:17:02 +0300
Subject: [PATCH 11/20] refactor(style): remove stylix theming

---
 flake.lock                           | 261 ---------------------------
 flake.nix                            |  15 --
 modules/hm-apps/flameshot.nix        |  16 +-
 modules/hm-apps/nixvim.nix           |   6 +-
 modules/style/stylix.nix             | 124 -------------
 modules/window-manager/i3-config.nix | 171 +++++++-----------
 6 files changed, 67 insertions(+), 526 deletions(-)
 delete mode 100644 modules/style/stylix.nix

diff --git a/flake.lock b/flake.lock
index 57b996a22..e3c7a5d8b 100644
--- a/flake.lock
+++ b/flake.lock
@@ -1,73 +1,5 @@
 {
   "nodes": {
-    "base16": {
-      "inputs": {
-        "fromYaml": "fromYaml"
-      },
-      "locked": {
-        "lastModified": 1755819240,
-        "narHash": "sha256-qcMhnL7aGAuFuutH4rq9fvAhCpJWVHLcHVZLtPctPlo=",
-        "owner": "SenchoPens",
-        "repo": "base16.nix",
-        "rev": "75ed5e5e3fce37df22e49125181fa37899c3ccd6",
-        "type": "github"
-      },
-      "original": {
-        "owner": "SenchoPens",
-        "repo": "base16.nix",
-        "type": "github"
-      }
-    },
-    "base16-fish": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1754405784,
-        "narHash": "sha256-l9xHIy+85FN+bEo6yquq2IjD1rSg9fjfjpyGP1W8YXo=",
-        "owner": "tomyun",
-        "repo": "base16-fish",
-        "rev": "23ae20a0093dca0d7b39d76ba2401af0ccf9c561",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tomyun",
-        "repo": "base16-fish",
-        "rev": "23ae20a0093dca0d7b39d76ba2401af0ccf9c561",
-        "type": "github"
-      }
-    },
-    "base16-helix": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1752979451,
-        "narHash": "sha256-0CQM+FkYy0fOO/sMGhOoNL80ftsAzYCg9VhIrodqusM=",
-        "owner": "tinted-theming",
-        "repo": "base16-helix",
-        "rev": "27cf1e66e50abc622fb76a3019012dc07c678fac",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "base16-helix",
-        "type": "github"
-      }
-    },
-    "base16-vim": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1732806396,
-        "narHash": "sha256-e0bpPySdJf0F68Ndanwm+KWHgQiZ0s7liLhvJSWDNsA=",
-        "owner": "tinted-theming",
-        "repo": "base16-vim",
-        "rev": "577fe8125d74ff456cf942c733a85d769afe58b7",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "base16-vim",
-        "rev": "577fe8125d74ff456cf942c733a85d769afe58b7",
-        "type": "github"
-      }
-    },
     "cloudflare-go": {
       "flake": false,
       "locked": {
@@ -244,22 +176,6 @@
         "type": "github"
       }
     },
-    "firefox-gnome-theme": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1758112371,
-        "narHash": "sha256-lizRM2pj6PHrR25yimjyFn04OS4wcdbc38DCdBVa2rk=",
-        "owner": "rafaelmardojai",
-        "repo": "firefox-gnome-theme",
-        "rev": "0909cfe4a2af8d358ad13b20246a350e14c2473d",
-        "type": "github"
-      },
-      "original": {
-        "owner": "rafaelmardojai",
-        "repo": "firefox-gnome-theme",
-        "type": "github"
-      }
-    },
     "flake-compat": {
       "flake": false,
       "locked": {
@@ -296,27 +212,6 @@
         "type": "github"
       }
     },
-    "flake-parts_2": {
-      "inputs": {
-        "nixpkgs-lib": [
-          "stylix",
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1756770412,
-        "narHash": "sha256-+uWLQZccFHwqpGqr2Yt5VsW/PbeJVTn9Dk6SHWhNRPw=",
-        "owner": "hercules-ci",
-        "repo": "flake-parts",
-        "rev": "4524271976b625a4a605beefd893f270620fd751",
-        "type": "github"
-      },
-      "original": {
-        "owner": "hercules-ci",
-        "repo": "flake-parts",
-        "type": "github"
-      }
-    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -335,22 +230,6 @@
         "type": "github"
       }
     },
-    "fromYaml": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1731966426,
-        "narHash": "sha256-lq95WydhbUTWig/JpqiB7oViTcHFP8Lv41IGtayokA8=",
-        "owner": "SenchoPens",
-        "repo": "fromYaml",
-        "rev": "106af9e2f715e2d828df706c386a685698f3223b",
-        "type": "github"
-      },
-      "original": {
-        "owner": "SenchoPens",
-        "repo": "fromYaml",
-        "type": "github"
-      }
-    },
     "git-hooks": {
       "inputs": {
         "flake-compat": [
@@ -396,23 +275,6 @@
         "type": "github"
       }
     },
-    "gnome-shell": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1748186689,
-        "narHash": "sha256-UaD7Y9f8iuLBMGHXeJlRu6U1Ggw5B9JnkFs3enZlap0=",
-        "owner": "GNOME",
-        "repo": "gnome-shell",
-        "rev": "8c88f917db0f1f0d80fa55206c863d3746fa18d0",
-        "type": "github"
-      },
-      "original": {
-        "owner": "GNOME",
-        "ref": "48.2",
-        "repo": "gnome-shell",
-        "type": "github"
-      }
-    },
     "home-manager": {
       "inputs": {
         "nixpkgs": [
@@ -699,8 +561,6 @@
         "sink-rotate": "sink-rotate",
         "smart-scrolloff-nvim": "smart-scrolloff-nvim",
         "sops-nix": "sops-nix",
-        "stylix": "stylix",
-        "tinted-schemes": "tinted-schemes",
         "treefmt-nix": "treefmt-nix",
         "ucodenix": "ucodenix",
         "vim-autoread": "vim-autoread",
@@ -786,46 +646,6 @@
         "type": "github"
       }
     },
-    "stylix": {
-      "inputs": {
-        "base16": "base16",
-        "base16-fish": "base16-fish",
-        "base16-helix": "base16-helix",
-        "base16-vim": "base16-vim",
-        "firefox-gnome-theme": "firefox-gnome-theme",
-        "flake-parts": "flake-parts_2",
-        "gnome-shell": "gnome-shell",
-        "nixpkgs": [
-          "nixpkgs"
-        ],
-        "nur": [
-          "dedupe_nur"
-        ],
-        "systems": [
-          "dedupe_systems"
-        ],
-        "tinted-foot": "tinted-foot",
-        "tinted-kitty": "tinted-kitty",
-        "tinted-schemes": [
-          "tinted-schemes"
-        ],
-        "tinted-tmux": "tinted-tmux",
-        "tinted-zed": "tinted-zed"
-      },
-      "locked": {
-        "lastModified": 1760472212,
-        "narHash": "sha256-4C3I/ssFsq8EgaUmZP0xv5V7RV0oCHgL/Rx+MUkuE+E=",
-        "owner": "nix-community",
-        "repo": "stylix",
-        "rev": "8d008296a1b3be9b57ad570f7acea00dd2fc92db",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-community",
-        "repo": "stylix",
-        "type": "github"
-      }
-    },
     "systems": {
       "locked": {
         "lastModified": 1681028828,
@@ -856,87 +676,6 @@
         "type": "github"
       }
     },
-    "tinted-foot": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1726913040,
-        "narHash": "sha256-+eDZPkw7efMNUf3/Pv0EmsidqdwNJ1TaOum6k7lngDQ=",
-        "owner": "tinted-theming",
-        "repo": "tinted-foot",
-        "rev": "fd1b924b6c45c3e4465e8a849e67ea82933fcbe4",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "tinted-foot",
-        "rev": "fd1b924b6c45c3e4465e8a849e67ea82933fcbe4",
-        "type": "github"
-      }
-    },
-    "tinted-kitty": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1735730497,
-        "narHash": "sha256-4KtB+FiUzIeK/4aHCKce3V9HwRvYaxX+F1edUrfgzb8=",
-        "owner": "tinted-theming",
-        "repo": "tinted-kitty",
-        "rev": "de6f888497f2c6b2279361bfc790f164bfd0f3fa",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "tinted-kitty",
-        "type": "github"
-      }
-    },
-    "tinted-schemes": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1757716333,
-        "narHash": "sha256-d4km8W7w2zCUEmPAPUoLk1NlYrGODuVa3P7St+UrqkM=",
-        "owner": "tinted-theming",
-        "repo": "schemes",
-        "rev": "317a5e10c35825a6c905d912e480dfe8e71c7559",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "schemes",
-        "type": "github"
-      }
-    },
-    "tinted-tmux": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1757811970,
-        "narHash": "sha256-n5ZJgmzGZXOD9pZdAl1OnBu3PIqD+X3vEBUGbTi4JiI=",
-        "owner": "tinted-theming",
-        "repo": "tinted-tmux",
-        "rev": "d217ba31c846006e9e0ae70775b0ee0f00aa6b1e",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "tinted-tmux",
-        "type": "github"
-      }
-    },
-    "tinted-zed": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1757811247,
-        "narHash": "sha256-4EFOUyLj85NRL3OacHoLGEo0wjiRJzfsXtR4CZWAn6w=",
-        "owner": "tinted-theming",
-        "repo": "base16-zed",
-        "rev": "824fe0aacf82b3c26690d14e8d2cedd56e18404e",
-        "type": "github"
-      },
-      "original": {
-        "owner": "tinted-theming",
-        "repo": "base16-zed",
-        "type": "github"
-      }
-    },
     "treefmt-nix": {
       "inputs": {
         "nixpkgs": [
diff --git a/flake.nix b/flake.nix
index 6356e9645..09e3b247d 100644
--- a/flake.nix
+++ b/flake.nix
@@ -99,16 +99,6 @@
       url = "github:tonymajestro/smart-scrolloff.nvim";
     };
 
-    stylix = {
-      url = "github:nix-community/stylix";
-      inputs = {
-        nixpkgs.follows = "nixpkgs";
-        nur.follows = "dedupe_nur";
-        systems.follows = "dedupe_systems";
-        tinted-schemes.follows = "tinted-schemes";
-      };
-    };
-
     # Official Cloudflare language SDKs as sources (non-flake repos)
     cloudflare-go = {
       flake = false;
@@ -131,11 +121,6 @@
       url = "github:cloudflare/workers-rs";
     };
 
-    tinted-schemes = {
-      flake = false;
-      url = "github:tinted-theming/schemes";
-    };
-
     treefmt-nix = {
       url = "github:numtide/treefmt-nix";
       inputs.nixpkgs.follows = "nixpkgs";
diff --git a/modules/hm-apps/flameshot.nix b/modules/hm-apps/flameshot.nix
index de292a380..10b11fc99 100644
--- a/modules/hm-apps/flameshot.nix
+++ b/modules/hm-apps/flameshot.nix
@@ -30,16 +30,8 @@
       ...
     }:
     let
-      stylixColors = lib.attrByPath [ "lib" "stylix" "colors" ] { } config;
-      stylixColorsWithHash = lib.attrByPath [ "withHashtag" ] { } stylixColors;
-      getColor =
-        name:
-        if lib.hasAttr name stylixColorsWithHash then
-          stylixColorsWithHash.${name}
-        else if lib.hasAttr name stylixColors then
-          stylixColors.${name}
-        else
-          "#740096";
+      uiColorDefault = "#740096";
+      contrastUiColorDefault = "#1B1B1B";
       picturesDirRaw = config.xdg.userDirs.pictures or null;
       picturesDir =
         if picturesDirRaw == null then "${config.home.homeDirectory}/Pictures" else picturesDirRaw;
@@ -63,8 +55,8 @@
             copyPathAfterSave = true;
             savePath = screenshotDir;
             savePathFixed = true;
-            uiColor = getColor "base0D";
-            contrastUiColor = getColor "base01";
+            uiColor = uiColorDefault;
+            contrastUiColor = contrastUiColorDefault;
           };
         };
       };
diff --git a/modules/hm-apps/nixvim.nix b/modules/hm-apps/nixvim.nix
index feedcbf85..42fd1b464 100644
--- a/modules/hm-apps/nixvim.nix
+++ b/modules/hm-apps/nixvim.nix
@@ -7,10 +7,10 @@
 
   Summary:
     * Exposes Neovim configuration as Nix options so editor state, plugins, and key maps stay reproducible.
-    * Provides first-class modules for plugin ecosystems (treesitter, LSP, UI helpers) and integrates with Stylix theming targets.
+    * Provides first-class modules for plugin ecosystems (treesitter, LSP, UI helpers) with declarative configuration.
 
   Notes:
-    * Imports the upstream Home Manager nixvim module from `inputs.nixvim` and layers Stylix’ nixvim target when enabled.
+    * Imports the upstream Home Manager nixvim module from `inputs.nixvim` and configures plugins declaratively.
     * Ships the `glow.nvim` preview plugin with Markdown-only lazy loading and convenient preview keymaps.
 */
 
@@ -50,8 +50,6 @@
     {
       imports = [ inputs.nixvim.homeModules.nixvim ];
 
-      stylix.targets.nixvim.enable = mkDefault true;
-
       programs.nixvim = {
         enable = true;
         globals.mapleader = mkDefault " ";
diff --git a/modules/style/stylix.nix b/modules/style/stylix.nix
deleted file mode 100644
index cfb559918..000000000
--- a/modules/style/stylix.nix
+++ /dev/null
@@ -1,124 +0,0 @@
-{
-  inputs,
-  lib,
-  ...
-}:
-{
-  flake = {
-    nixosModules = {
-      base = {
-        imports = [ inputs.stylix.nixosModules.stylix ];
-        stylix = {
-          enable = true;
-          homeManagerIntegration.autoImport = false;
-          # Use OneDark theme by default
-          base16Scheme = lib.mkDefault "${inputs.tinted-schemes}/base16/onedark.yaml";
-          polarity = lib.mkDefault "dark";
-          targets.grub.enable = false;
-        };
-      };
-
-      workstation =
-        { pkgs, ... }:
-        {
-          stylix = {
-            # Opacity settings for desktop systems
-            opacity = lib.genAttrs [ "applications" "desktop" "popups" "terminal" ] (_n: 1.0);
-
-            # Font configuration for desktop systems
-            fonts = {
-              sansSerif = lib.mkDefault {
-                package = pkgs.nerd-fonts.fira-code;
-                name = "Fira Code Nerd Font";
-              };
-              serif = lib.mkDefault {
-                package = pkgs.nerd-fonts.fira-code;
-                name = "Fira Code Nerd Font";
-              };
-              monospace = {
-                package = pkgs.nerd-fonts.fira-code;
-                name = "Fira Code Nerd Font";
-              };
-              emoji = {
-                package = pkgs.fira-code-symbols;
-                name = "Fira Code Symbols";
-              };
-              sizes = {
-                applications = 12;
-                desktop = 12;
-                popups = 12;
-                terminal = 12;
-              };
-            };
-          };
-          fonts.fontconfig.enable = true;
-        };
-
-      # end of nixosModules
-    };
-
-    homeManagerModules = {
-      base = {
-        imports = [ inputs.stylix.homeModules.stylix ];
-        stylix = {
-          enable = true;
-          # Use OneDark theme by default
-          base16Scheme = lib.mkDefault "${inputs.tinted-schemes}/base16/onedark.yaml";
-          polarity = lib.mkDefault "dark";
-
-        };
-      };
-
-      gui =
-        { pkgs, ... }:
-        {
-          stylix = {
-            # Opacity settings for GUI applications
-            opacity = lib.genAttrs [ "applications" "desktop" "popups" "terminal" ] (_n: 1.0);
-
-            # Font configuration for GUI applications
-            fonts = {
-              sansSerif = lib.mkDefault {
-                package = pkgs.fira-code;
-                name = "Fira Code";
-              };
-              serif = lib.mkDefault {
-                package = pkgs.fira-code;
-                name = "Fira Code";
-              };
-              monospace = {
-                package = pkgs.nerd-fonts.fira-code;
-                name = "Fira Code Nerd Font";
-              };
-              emoji = {
-                package = pkgs.fira-code-symbols;
-                name = "Fira Code symbols";
-              };
-              sizes = {
-                applications = 12;
-                desktop = 12;
-                popups = 12;
-                terminal = 12;
-              };
-            };
-
-            # Firefox profile theming
-            targets.firefox.profileNames = [ "primary" ];
-            targets.firefox.firefoxGnomeTheme.enable = true;
-          };
-
-          # Additional font packages
-          home.packages = [
-            pkgs.google-fonts
-            pkgs.gucharmap
-            pkgs.nerd-fonts.jetbrains-mono
-          ];
-        };
-    };
-
-    lib.nixvim.astrea = nixvimArgs: {
-      # https://github.com/danth/stylix/pull/415#issuecomment-2832398958
-      imports = lib.optional (nixvimArgs ? homeConfig) nixvimArgs.homeConfig.lib.stylix.nixvim.config;
-    };
-  };
-}
diff --git a/modules/window-manager/i3-config.nix b/modules/window-manager/i3-config.nix
index b3c5fd93a..f213805be 100644
--- a/modules/window-manager/i3-config.nix
+++ b/modules/window-manager/i3-config.nix
@@ -177,27 +177,18 @@
         screenshot = "${lib.getExe pkgs.maim} -s -u | ${lib.getExe pkgs.xclip} -selection clipboard -t image/png -i";
         logseqToggle = lib.getExe toggleLogseqScript;
       };
-      # Unconditional Stylix colors (Stylix is always available)
-      stylixColorsStrict = config.lib.stylix.colors;
-      stylixColorsStrictWithHash = stylixColorsStrict.withHashtag or stylixColorsStrict;
-      toLockColor =
-        colorHex:
-        let
-          trimmed = lib.removePrefix "#" colorHex;
-          normalized = if builtins.stringLength trimmed == 8 then trimmed else trimmed + "FF";
-        in
-        lib.strings.toUpper normalized;
-      # Build lock palette directly from Stylix colors (no fallbacks)
+      # Static palette used for the custom lock command
       lockPalette = {
-        background = toLockColor stylixColorsStrictWithHash.base00;
-        ring = toLockColor stylixColorsStrictWithHash.base04;
-        ringWrong = toLockColor stylixColorsStrictWithHash.base08;
-        ringVerify = toLockColor stylixColorsStrictWithHash.base0B;
-        line = toLockColor stylixColorsStrictWithHash.base03;
-        text = toLockColor stylixColorsStrictWithHash.base05;
+        background = "1e1e2eff";
+        ring = "7aa2f7ff";
+        ringWrong = "f7768eff";
+        ringVerify = "9ece6aff";
+        line = "414868ff";
+        text = "d0d5f0ff";
       };
+      defaultBackgroundColor = "#1e1e2e";
       lockScript = pkgs.writeShellApplication {
-        name = "i3lock-stylix";
+        name = "i3lock-custom";
         runtimeInputs = [
           pkgs.i3lock-color
           pkgs.procps
@@ -305,60 +296,50 @@
           format = " $icon $timestamp.datetime(f:'%a %d/%m %R') ";
         }
       ];
-      i3statusBarConfig =
-        let
-          stylixThemeOverrides = lib.attrByPath [ "lib" "stylix" "i3status-rust" "bar" ] { } config;
-        in
-        {
-          blocks = i3statusBlocks;
-          settings = {
-            icons = {
-              icons = "awesome6";
-              overrides = {
-                cpu = "";
-                update = "";
-                temp = [
-                  ""
-                  ""
-                  ""
-                ];
-                volume = [
-                  ""
-                  ""
-                  ""
-                ];
-                volume_muted = "";
-                bat = [
-                  ""
-                  ""
-                  ""
-                  ""
-                  ""
-                ];
-                bat_charging = "";
-                net_wireless = [
-                  "▂"
-                  "▃"
-                  "▅"
-                  "▇"
-                  ""
-                ];
-                net_wired = "";
-                net_down = "";
-                net_up = "";
-                net_vpn = "";
-                net_loopback = "";
-                net_unknown = "";
-              };
-            };
-          }
-          // lib.optionalAttrs (stylixThemeOverrides != { }) {
-            theme = {
-              theme = "plain";
-              overrides = stylixThemeOverrides;
+      i3statusBarConfig = {
+        blocks = i3statusBlocks;
+        settings = {
+          icons = {
+            icons = "awesome6";
+            overrides = {
+              cpu = "";
+              update = "";
+              temp = [
+                ""
+                ""
+                ""
+              ];
+              volume = [
+                ""
+                ""
+                ""
+              ];
+              volume_muted = "";
+              bat = [
+                ""
+                ""
+                ""
+                ""
+                ""
+              ];
+              bat_charging = "";
+              net_wireless = [
+                "▂"
+                "▃"
+                "▅"
+                "▇"
+                ""
+              ];
+              net_wired = "";
+              net_down = "";
+              net_up = "";
+              net_vpn = "";
+              net_loopback = "";
+              net_unknown = "";
             };
           };
         };
+      };
       workspaceOutputAssign = [
         {
           workspace = "1";
@@ -455,13 +436,11 @@
           bars.default = i3statusBarConfig;
         };
 
-        stylix.targets.i3.enable = lib.mkDefault true;
-
         xdg.configFile = {
           "i3status-rust/config.toml".source =
             config.xdg.configFile."i3status-rust/config-default.toml".source;
 
-          "i3/scripts/i3lock-stylix" = {
+          "i3/scripts/i3lock-custom" = {
             executable = true;
             text = ''
               #!/usr/bin/env bash
@@ -494,7 +473,7 @@
 
               startup = lib.mkAfter [
                 {
-                  command = "${lib.getExe' pkgs.hsetroot "hsetroot"} -solid '${stylixColorsStrictWithHash.base00}'";
+                  command = "${lib.getExe' pkgs.hsetroot "hsetroot"} -solid '${defaultBackgroundColor}'";
                   always = true;
                   notification = false;
                 }
@@ -517,31 +496,6 @@
                 titlebar = false;
               };
 
-              # Make split-direction hint use the same color as borders
-              # (indicator equals border per state). Keep scope minimal and
-              # avoid self-referencing config to prevent recursion.
-              colors = {
-                focused.indicator = lib.mkForce stylixColorsStrictWithHash.base0D;
-                urgent.indicator = lib.mkForce stylixColorsStrictWithHash.base08;
-
-                # Grouped per-state overrides to satisfy linters and avoid repetition
-                focusedInactive = {
-                  indicator = lib.mkForce stylixColorsStrictWithHash.base00;
-                  border = lib.mkForce stylixColorsStrictWithHash.base00;
-                  childBorder = lib.mkForce stylixColorsStrictWithHash.base00;
-                };
-                unfocused = {
-                  indicator = lib.mkForce stylixColorsStrictWithHash.base03;
-                  border = lib.mkForce stylixColorsStrictWithHash.base00;
-                  childBorder = lib.mkForce stylixColorsStrictWithHash.base00;
-                };
-                placeholder = {
-                  indicator = lib.mkForce stylixColorsStrictWithHash.base03;
-                  border = lib.mkForce stylixColorsStrictWithHash.base00;
-                  childBorder = lib.mkForce stylixColorsStrictWithHash.base00;
-                };
-              };
-
               workspaceAutoBackAndForth = true;
               inherit workspaceOutputAssign;
 
@@ -553,18 +507,15 @@
               };
 
               bars = [
-                (
-                  {
-                    mode = "dock";
-                    hiddenState = "hide";
-                    position = "top";
-                    trayOutput = "primary";
-                    workspaceButtons = true;
-                    workspaceNumbers = true;
-                    statusCommand = lib.getExe pkgs.i3status-rust;
-                  }
-                  // config.stylix.targets.i3.exportedBarConfig
-                )
+                {
+                  mode = "dock";
+                  hiddenState = "hide";
+                  position = "top";
+                  trayOutput = "primary";
+                  workspaceButtons = true;
+                  workspaceNumbers = true;
+                  statusCommand = lib.getExe pkgs.i3status-rust;
+                }
               ];
 
               assigns = lib.mkOptionDefault {

From 109ea04f790503fcfb1b45ca573c22659ab22bcb Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 12:17:46 +0300
Subject: [PATCH 12/20] chore: update docs

---
 AGENTS.md                                  | 1 -
 CLAUDE.md                                  | 1 -
 docs/system76-home-manager-observations.md | 8 ++++----
 3 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5900b7f64..2785fea8e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -104,7 +104,6 @@ Pause, summarize the situation, and ask vx for direction before proceeding.
 
 | Name           | Path                       | Use When                                                          |
 | -------------- | -------------------------- | ----------------------------------------------------------------- |
-| Stylix         | `$HOME/git/stylix`         | Inspect Stylix source or apply local patches.                     |
 | Home Manager   | `$HOME/git/home-manager`   | Review module behaviors or backport fixes.                        |
 | i3 Docs        | `$HOME/git/i3wm-docs`      | Reference i3 window manager documentation offline.                |
 | nixpkgs        | `$HOME/git/nixpkgs`        | Vendor patches or inspect upstream expressions.                   |
diff --git a/CLAUDE.md b/CLAUDE.md
index 9ced13284..95c9ec723 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -154,7 +154,6 @@ Pause, summarize the situation, and ask vx for direction before proceeding.
 
 | Name           | Path                       | Use When                                                          |
 | -------------- | -------------------------- | ----------------------------------------------------------------- |
-| Stylix         | `$HOME/git/stylix`         | Inspect Stylix source or apply local patches.                     |
 | Home Manager   | `$HOME/git/home-manager`   | Review module behaviors or backport fixes.                        |
 | i3 Docs        | `$HOME/git/i3wm-docs`      | Reference i3 window manager documentation offline.                |
 | nixpkgs        | `$HOME/git/nixpkgs`        | Vendor patches or inspect upstream expressions.                   |
diff --git a/docs/system76-home-manager-observations.md b/docs/system76-home-manager-observations.md
index a27248a48..d26d738e3 100644
--- a/docs/system76-home-manager-observations.md
+++ b/docs/system76-home-manager-observations.md
@@ -7,11 +7,11 @@ System76’s NixOS host does import the workstation bundle and the System76‑sp
 ## Key Observations
 
 - `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager'` returns an attrset with just `extraAppImports`, confirming the broader Home Manager config never materialises.
-- Querying `config.home-manager.users` via  
-  `nix eval --accept-flake-config --impure --expr 'let flake = builtins.getFlake (toString ./.) ; in flake.nixosConfigurations.system76.config.home-manager.users'`  
+- Querying `config.home-manager.users` via
+  `nix eval --accept-flake-config --impure --expr 'let flake = builtins.getFlake (toString ./.) ; in flake.nixosConfigurations.system76.config.home-manager.users'`
   fails with `attribute 'users' missing`; the owner import from `modules/home-manager/nixos.nix` never ran.
-- The module args visible during host evaluation omit flake inputs:  
-  `nix eval --accept-flake-config '.#nixosConfigurations.system76._module.args' --apply builtins.attrNames`  
+- The module args visible during host evaluation omit flake inputs:
+  `nix eval --accept-flake-config '.#nixosConfigurations.system76._module.args' --apply builtins.attrNames`
   → `[ "baseModules" "extendModules" "extraModules" "moduleType" "modules" "noUserModules" "pkgs" "utils" ]`.
 - `_module.specialArgs` confirms only the default `modulesPath` is passed through (`nix eval … '_module.specialArgs'`), so no `inputs`/`self` reach downstream modules.
 - `modules/system76/imports.nix` builds `nixosConfigurations.system76` by calling `inputs.nixpkgs.lib.nixosSystem { modules = [ … config.configurations.nixos.system76.module ]; }` without any `specialArgs`. Because of that, the module system never seeds `_module.args.inputs`, and the Home Manager glue’s lookup of `flake.homeManagerModules.base` fails.

From 1f2deb1641fdee294a2107cb9a14d43fd694a8ac Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 20 Oct 2025 12:22:42 +0300
Subject: [PATCH 13/20] fix: scaffold

---
 debug/system76-home-manager-scaffold.nix | 37 ++++++++++++------------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/debug/system76-home-manager-scaffold.nix b/debug/system76-home-manager-scaffold.nix
index 01e79492d..fda7eddce 100644
--- a/debug/system76-home-manager-scaffold.nix
+++ b/debug/system76-home-manager-scaffold.nix
@@ -1,15 +1,11 @@
+# statix:ignore-file
 {
   flake ? builtins.getFlake (toString ./.),
   lib ? flake.inputs.nixpkgs.lib,
 }:
 let
-  baseModules = flake.nixosConfigurations.system76._module.args.modules;
-  specialArgsBase = flake.nixosConfigurations.system76._module.specialArgs;
-  specialArgs = specialArgsBase // {
-    inputs = flake.inputs;
-    self = flake;
-  };
-
+  inherit (flake.nixosConfigurations.system76) _module;
+  sourceModules = _module.args.modules;
   freeform = lib.types.attrsOf lib.types.anything;
 
   mkNamespaceOption =
@@ -74,11 +70,11 @@ let
       config.debug.hmTrace.${label} = msg;
     };
 
-  first = builtins.elemAt baseModules 0;
-  top = builtins.elemAt baseModules 1;
-  last = builtins.elemAt baseModules 2;
+  first = builtins.elemAt sourceModules 0;
+  top = builtins.elemAt sourceModules 1;
+  last = builtins.elemAt sourceModules 2;
 
-  imports = top.imports;
+  inherit (top) imports;
 
   pairs = lib.imap (index: module: {
     inherit module;
@@ -90,14 +86,6 @@ let
     (mkTraceModule pair.label)
   ]) pairs;
 
-  modules = [
-    scaffoldModule
-    first
-    (mkTraceModule "pre-system76")
-    (top // { imports = interleaved; })
-    last
-  ];
-
   baseTop = flake.nixosModules.base;
   baseImports = baseTop.imports;
 
@@ -118,6 +106,17 @@ let
     scaffoldModule
     baseModule
   ];
+  modules = [
+    scaffoldModule
+    first
+    (mkTraceModule "pre-system76")
+    (top // { imports = interleaved; })
+    last
+  ];
+  specialArgs = _module.specialArgs // {
+    inherit (flake) inputs;
+    self = flake;
+  };
 in
 {
   inherit

From a8e9ba9c4ceafc814e93c572a91a2f94b2b8df27 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Tue, 21 Oct 2025 14:11:17 +0300
Subject: [PATCH 14/20] commit a stage..

---
 debug/flake-nixosModules-reproducer.nix      |  59 ++++
 debug/system76-home-manager-scaffold.nix     | 343 +++++++++++++++++--
 docs/system76-home-manager-observations.md   |  25 +-
 modules/hardware/monitors/lenovo-y27q-20.nix |   1 +
 modules/home-manager/nixos.nix               |  16 +-
 modules/meta/flake-output.nix                |   4 +
 modules/meta/nixos-app-helpers.nix           |   9 +-
 modules/meta/nixos-helpers.nix               |   8 +
 modules/meta/nixos-role-helpers.nix          |  54 ++-
 modules/meta/nixos-roles-import.nix          |   6 +
 modules/meta/nixos-roles-preload.nix         |  19 +
 modules/system76/imports.nix                 |  19 +-
 notes.md                                     |   4 +
 13 files changed, 517 insertions(+), 50 deletions(-)
 create mode 100644 debug/flake-nixosModules-reproducer.nix
 create mode 100644 modules/meta/nixos-helpers.nix
 create mode 100644 modules/meta/nixos-roles-import.nix
 create mode 100644 modules/meta/nixos-roles-preload.nix
 create mode 100644 notes.md

diff --git a/debug/flake-nixosModules-reproducer.nix b/debug/flake-nixosModules-reproducer.nix
new file mode 100644
index 000000000..e32699d19
--- /dev/null
+++ b/debug/flake-nixosModules-reproducer.nix
@@ -0,0 +1,59 @@
+{
+  flake ? builtins.getFlake (toString ./..),
+  lib ? flake.inputs.nixpkgs.lib,
+}:
+let
+  optionStub =
+    { lib, ... }:
+    {
+      options.flake.nixosModules = lib.mkOption {
+        type = lib.types.lazyAttrsOf lib.types.anything;
+        default = { };
+        description = "Debug stub: defines flake.nixosModules so downstream modules can assign into it.";
+      };
+      options.flake.lib = lib.mkOption {
+        type = lib.types.attrsOf lib.types.anything;
+        default = { };
+        description = "Debug stub: allows modules to write helpers under flake.lib.*";
+      };
+      config.flake.nixosModules = lib.mkDefault { };
+      config.flake.lib = lib.mkDefault { };
+    };
+
+  roleModule =
+    { lib, ... }:
+    {
+      config.flake.nixosModules.roles = {
+        xserver = {
+          imports = [
+            (_: { })
+          ];
+        };
+      };
+    };
+
+  evalWithoutStub = builtins.tryEval (
+    lib.evalModules {
+      modules = [ roleModule ];
+      specialArgs = { inherit lib; };
+    }
+  );
+
+  evalWithStub = builtins.tryEval (
+    lib.evalModules {
+      modules = [
+        optionStub
+        roleModule
+      ];
+      specialArgs = { inherit lib; };
+    }
+  );
+in
+{
+  inherit
+    optionStub
+    roleModule
+    evalWithoutStub
+    evalWithStub
+    ;
+}
diff --git a/debug/system76-home-manager-scaffold.nix b/debug/system76-home-manager-scaffold.nix
index fda7eddce..7e611e2e2 100644
--- a/debug/system76-home-manager-scaffold.nix
+++ b/debug/system76-home-manager-scaffold.nix
@@ -5,8 +5,98 @@
 }:
 let
   inherit (flake.nixosConfigurations.system76) _module;
-  sourceModules = _module.args.modules;
+  sourceModulesResult = builtins.tryEval _module.args.modules;
+  sourceModules = if sourceModulesResult.success then sourceModulesResult.value else [ ];
+  sourceModulesWithBootstrap = [ optionBootstrapModule ] ++ sourceModules;
   freeform = lib.types.attrsOf lib.types.anything;
+  roleDir = ./../modules/roles;
+  appsDir = ./../modules/apps;
+  langDir = ./../modules/languages;
+  windowManagerDir = ./../modules/window-manager;
+  roleNames =
+    let
+      entries = builtins.readDir roleDir;
+      names = builtins.filter (name: entries.${name} == "regular" && lib.hasSuffix ".nix" name) (
+        builtins.attrNames entries
+      );
+    in
+    builtins.map (name: lib.removeSuffix ".nix" name) names;
+  appNames =
+    let
+      entries = builtins.readDir appsDir;
+      files = builtins.filter (name: entries.${name} == "regular" && lib.hasSuffix ".nix" name) (
+        builtins.attrNames entries
+      );
+    in
+    builtins.map (name: lib.removeSuffix ".nix" name) files;
+  langNames =
+    let
+      entries = if builtins.pathExists langDir then builtins.readDir langDir else { };
+      files = builtins.filter (name: entries.${name} == "regular" && lib.hasSuffix ".nix" name) (
+        builtins.attrNames entries
+      );
+      trim =
+        name:
+        let
+          withoutSuffix = lib.removeSuffix ".nix" name;
+        in
+        if lib.hasPrefix "lang-" withoutSuffix then
+          builtins.substring 5 (builtins.stringLength withoutSuffix - 5) withoutSuffix
+        else
+          withoutSuffix;
+    in
+    builtins.map trim files;
+  windowManagerNames =
+    let
+      entries = builtins.readDir windowManagerDir;
+      files = builtins.filter (name: entries.${name} == "regular" && lib.hasSuffix ".nix" name) (
+        builtins.attrNames entries
+      );
+    in
+    builtins.map (name: lib.removeSuffix ".nix" name) files;
+
+  mkExportOrStub =
+    filePath: path:
+    let
+      imported = import filePath;
+    in
+    if builtins.isAttrs imported && lib.hasAttrByPath path imported then
+      lib.getAttrFromPath path imported
+    else
+      (_: { });
+
+  mkAppStub =
+    name:
+    mkExportOrStub (appsDir + "/${name}.nix") [
+      "flake"
+      "nixosModules"
+      "apps"
+      name
+    ];
+
+  appStubs = lib.genAttrs appNames mkAppStub;
+
+  mkLangStub =
+    name:
+    mkExportOrStub (langDir + "/lang-${name}.nix") [
+      "flake"
+      "nixosModules"
+      "lang"
+      name
+    ];
+
+  langStubs = lib.genAttrs langNames mkLangStub;
+
+  mkWindowManagerStub =
+    name:
+    mkExportOrStub (windowManagerDir + "/${name}.nix") [
+      "flake"
+      "nixosModules"
+      "window-manager"
+      name
+    ];
+
+  windowManagerStubs = lib.genAttrs windowManagerNames mkWindowManagerStub;
 
   mkNamespaceOption =
     name:
@@ -16,16 +106,26 @@ let
       description = "${name} scaffold (debug only)";
     };
 
+  optionBootstrapModule =
+    (import ./flake-nixosModules-reproducer.nix { inherit flake lib; }).optionStub;
+
   scaffoldModule =
-    { lib, ... }:
+    { config, lib, ... }:
     let
       libStub = flake.lib or { };
+      inherit (config) system;
+      pkgs =
+        if lib.hasAttrByPath [ "legacyPackages" system ] flake.inputs.nixpkgs then
+          flake.inputs.nixpkgs.legacyPackages.${system}
+        else
+          import flake.inputs.nixpkgs { inherit system; };
     in
     {
       options = {
         flake = lib.mkOption {
-          type = lib.types.attrs;
-          default = flake;
+          type = lib.types.submodule { freeformType = freeform; };
+          default = { };
+          description = "Debug stub: start with an empty flake namespace; downstream modules populate nixosModules/lib as needed.";
         };
         nixpkgs = lib.mkOption {
           type = lib.types.submodule { freeformType = freeform; };
@@ -38,15 +138,37 @@ let
         boot = mkNamespaceOption "boot";
         environment = mkNamespaceOption "environment";
         services = mkNamespaceOption "services";
+        systemd = mkNamespaceOption "systemd";
         users = mkNamespaceOption "users";
         hardware = mkNamespaceOption "hardware";
         networking = mkNamespaceOption "networking";
         virtualisation = mkNamespaceOption "virtualisation";
+        console = mkNamespaceOption "console";
+        security = mkNamespaceOption "security";
+        programs = mkNamespaceOption "programs";
+        nix = mkNamespaceOption "nix";
+        fonts = mkNamespaceOption "fonts";
+        i18n = mkNamespaceOption "i18n";
+        time = mkNamespaceOption "time";
+        xdg = mkNamespaceOption "xdg";
+        sound = mkNamespaceOption "sound";
+        documentation = mkNamespaceOption "documentation";
+        home-manager = mkNamespaceOption "home-manager";
         lib = lib.mkOption {
           type = lib.types.attrs;
           default = libStub;
         };
-        debug.hmTrace = mkNamespaceOption "debug.hmTrace";
+        debug = {
+          hmTrace = mkNamespaceOption "debug.hmTrace";
+          argsTrace = mkNamespaceOption "debug.argsTrace";
+          roleProbe = mkNamespaceOption "debug.roleProbe";
+          flakeTrace = mkNamespaceOption "debug.flakeTrace";
+          flakeFinal = lib.mkOption {
+            type = lib.types.attrs;
+            default = { };
+            description = "Final flake.nixosModules snapshot (debug only)";
+          };
+        };
         assertions = lib.mkOption {
           type = lib.types.listOf lib.types.anything;
           default = [ ];
@@ -56,6 +178,7 @@ let
           default = [ ];
         };
       };
+      config._module.args.pkgs = lib.mkDefault pkgs;
     };
 
   mkTraceModule =
@@ -65,53 +188,202 @@ let
       hm = config.home-manager or { };
       names = builtins.attrNames hm;
       msg = if names == [ ] then "<empty>" else builtins.concatStringsSep ", " names;
+      moduleArgs = if config ? _module && config._module ? args then config._module.args else { };
+      argNames = builtins.attrNames moduleArgs;
+      argMsg = if argNames == [ ] then "<empty>" else builtins.concatStringsSep ", " argNames;
+      flakeModules =
+        if config ? flake && config.flake ? nixosModules then
+          builtins.attrNames config.flake.nixosModules
+        else
+          [ ];
+      flakeMsg = if flakeModules == [ ] then "<empty>" else builtins.concatStringsSep ", " flakeModules;
+      roleModules =
+        if config ? flake && config.flake ? nixosModules && config.flake.nixosModules ? roles then
+          builtins.attrNames config.flake.nixosModules.roles
+        else
+          [ ];
+      roleMsg = if roleModules == [ ] then "<empty>" else builtins.concatStringsSep ", " roleModules;
     in
     {
-      config.debug.hmTrace.${label} = msg;
+      config = {
+        debug = {
+          hmTrace.${label} = msg;
+          argsTrace.${label} = argMsg;
+          flakeTrace.${label} = {
+            nixosModules = flakeMsg;
+            roles = roleMsg;
+          };
+        };
+      };
+    };
+
+  stubModule =
+    { lib, self, ... }:
+    {
+      config.flake.nixosModules = lib.mkDefault (
+        let
+          selfModules = self.nixosModules or { };
+        in
+        selfModules
+        // {
+          apps = (selfModules.apps or { }) // appStubs;
+          lang = (selfModules.lang or { }) // langStubs;
+          "window-manager" = (selfModules."window-manager" or { }) // windowManagerStubs;
+        }
+      );
     };
 
-  first = builtins.elemAt sourceModules 0;
-  top = builtins.elemAt sourceModules 1;
-  last = builtins.elemAt sourceModules 2;
+  mkPairs =
+    prefix: modules:
+    lib.imap (index: module: {
+      inherit module;
+      label = prefix + "/" + builtins.toString index;
+    }) modules;
 
-  inherit (top) imports;
+  instrumentModule =
+    prefix: module:
+    if lib.isAttrs module && module ? imports then
+      module
+      // {
+        imports = instrumentImports prefix module.imports;
+      }
+    else
+      module;
 
-  pairs = lib.imap (index: module: {
-    inherit module;
-    label = "system76/" + builtins.toString index;
-  }) imports;
+  instrumentImports =
+    prefix: modules:
+    lib.concatMap (
+      pair:
+      let
+        annotated = instrumentModule pair.label pair.module;
+      in
+      [
+        annotated
+        (mkTraceModule pair.label)
+      ]
+    ) (mkPairs prefix modules);
 
-  interleaved = lib.concatMap (pair: [
-    pair.module
-    (mkTraceModule pair.label)
-  ]) pairs;
+  first = builtins.elemAt sourceModulesWithBootstrap 0;
+  top = builtins.elemAt sourceModulesWithBootstrap 1;
+  last = builtins.elemAt sourceModulesWithBootstrap 2;
+
+  roleProbeModule =
+    { config, lib, ... }:
+    let
+      finalFlake =
+        if config ? flake && config.flake ? nixosModules then
+          let
+            modulesAttr = config.flake.nixosModules;
+            rolesAttr =
+              modulesAttr.roles or (
+                if modulesAttr ? content && modulesAttr.content ? roles then modulesAttr.content.roles else { }
+              );
+            toNames = attr: if attr ? content then builtins.attrNames attr.content else builtins.attrNames attr;
+          in
+          {
+            nixosModules =
+              if modulesAttr ? content then
+                builtins.attrNames modulesAttr.content
+              else
+                builtins.attrNames modulesAttr;
+            roles = toNames rolesAttr;
+          }
+        else
+          {
+            nixosModules = [ ];
+            roles = [ ];
+          };
+      evalRole =
+        name:
+        let
+          roleExpr = import (roleDir + "/${name}.nix");
+          attempt =
+            if builtins.typeOf roleExpr == "lambda" then
+              builtins.tryEval (roleExpr {
+                inherit config lib;
+              })
+            else
+              builtins.tryEval roleExpr;
+          rolePath = [
+            "flake"
+            "nixosModules"
+            "roles"
+            name
+          ];
+        in
+        if attempt.success then
+          let
+            result = attempt.value;
+            rolePresent = if builtins.isAttrs result then lib.hasAttrByPath rolePath result else false;
+            payload = if rolePresent then lib.getAttrFromPath rolePath result else null;
+            payloadType = if payload == null then "none" else builtins.typeOf payload;
+            payloadEval =
+              if payloadType == "set" && builtins.isAttrs payload then
+                if payload ? imports then builtins.tryEval payload.imports else builtins.tryEval payload
+              else
+                {
+                  success = true;
+                  value = null;
+                };
+            resolvedKeys =
+              if payloadType == "set" then
+                builtins.attrNames payload
+              else if builtins.isAttrs result then
+                builtins.attrNames result
+              else
+                [ ];
+          in
+          {
+            success = true;
+            hasRoleAttr = rolePresent;
+            inherit payloadType;
+            keys = resolvedKeys;
+            payloadEvalSuccess = payloadEval.success;
+            payloadEvalError = if payloadEval.success then null else payloadEval.value;
+          }
+        else
+          {
+            success = false;
+            error = attempt.value;
+          };
+    in
+    {
+      config = {
+        debug = {
+          roleProbe = lib.genAttrs roleNames evalRole;
+          flakeFinal = finalFlake;
+        };
+      };
+    };
+
+  inherit (top) imports;
+
+  interleaved = instrumentImports "system76" imports;
 
   baseTop = flake.nixosModules.base;
   baseImports = baseTop.imports;
+  baseImportsWithBootstrap = [ optionBootstrapModule ] ++ baseImports;
 
-  basePairs = lib.imap (index: module: {
-    inherit module;
-    label = "base/" + builtins.toString index;
-  }) baseImports;
-
-  baseInterleaved = lib.concatMap (pair: [
-    pair.module
-    (mkTraceModule pair.label)
-  ]) basePairs;
+  baseInterleaved = instrumentImports "base" baseImportsWithBootstrap;
 
   baseModule = baseTop // {
     imports = baseInterleaved;
   };
   baseModulesForTrace = [
     scaffoldModule
+    stubModule
+    first
     baseModule
+    roleProbeModule
   ];
   modules = [
     scaffoldModule
+    stubModule
     first
     (mkTraceModule "pre-system76")
-    (top // { imports = interleaved; })
+    (top // { imports = [ optionBootstrapModule ] ++ interleaved; })
     last
+    roleProbeModule
   ];
   specialArgs = _module.specialArgs // {
     inherit (flake) inputs;
@@ -124,5 +396,20 @@ in
     specialArgs
     baseModule
     baseModulesForTrace
+    scaffoldModule
+    sourceModules
+    interleaved
+    first
+    top
+    last
+    ;
+  inherit
+    appNames
+    langNames
+    windowManagerNames
     ;
+  inherit optionBootstrapModule;
+  inherit baseImportsWithBootstrap sourceModulesWithBootstrap;
+  sourceModulesError = if sourceModulesResult.success then null else sourceModulesResult.value;
+  sourceModulesSuccess = sourceModulesResult.success;
 }
diff --git a/docs/system76-home-manager-observations.md b/docs/system76-home-manager-observations.md
index d26d738e3..5c8bfced6 100644
--- a/docs/system76-home-manager-observations.md
+++ b/docs/system76-home-manager-observations.md
@@ -16,6 +16,26 @@ System76’s NixOS host does import the workstation bundle and the System76‑sp
 - `_module.specialArgs` confirms only the default `modulesPath` is passed through (`nix eval … '_module.specialArgs'`), so no `inputs`/`self` reach downstream modules.
 - `modules/system76/imports.nix` builds `nixosConfigurations.system76` by calling `inputs.nixpkgs.lib.nixosSystem { modules = [ … config.configurations.nixos.system76.module ]; }` without any `specialArgs`. Because of that, the module system never seeds `_module.args.inputs`, and the Home Manager glue’s lookup of `flake.homeManagerModules.base` fails.
 - Inspecting `flake.outputs.nixosModules.base` directly shows the Home Manager glue is already missing **before** the role helper runs: every entry— including `modules/home-manager/nixos.nix`—exposes only `_file` and `imports`, with no `flake.homeManagerModules` or `config.home-manager` payload. This confirms the loss happens upstream of the role sanitisation.
+- The extended scaffold (`debug/system76-home-manager-scaffold.nix`) now seeds `_module.args.pkgs` plus stub namespaces so `lib.evalModules` can evaluate `flake.nixosModules.base` in isolation; every traced import under that bundle leaves `config.home-manager` with the full key set (`backupFileExtension`, `enableLegacyProfileManagement`, `overwriteBackup`, `useUserPackages`, `verbose`, …).
+- Feeding the same scaffold the real System76 import graph shows the very first checkpoint—`pre-system76`, taken immediately after the flake-provided prelude—already trimmed to `backupFileExtension, extraAppImports, extraSpecialArgs, sharedModules, useGlobalPkgs, users`, and none of the deeper labels ever restore the missing keys. The collapse therefore precedes any System76 overlay module.
+- Attempting to read `_module.args.inputs` from the live host still fails (`attribute 'inputs' missing`), confirming those helpers never reach the evaluation despite the scaffold supplying them manually.
+- Option inspection confirms that, after the System76 overlays are applied, the module system no longer registers `options.home-manager.*` entries at all—the attrset collapses to whatever the overlays append, leaving the base definitions (e.g. `enableLegacyProfileManagement`, `overwriteBackup`, `useUserPackages`, `verbose`) absent from both `options` and `config`.
+- Runtime probing (`lib.evalModules` with an inline helper) shows `_module.args.nixosRoleHelpers` is **absent** during the System76 evaluation, so `modules/workstation.nix` falls back to `config.flake.nixosModules.roles` when resolving `base`. The helper namespace (`config.flake.lib.nixos.roles`) still exposes `base`, which explains why the workstation stack continues to pull application modules while the dedicated role helpers—and their glue wiring—never run.
+- A recursive sweep of `nixosConfigurations.system76._module.args.modules` finds no module originating from `modules/meta/nixos-role-helpers.nix` or `modules/meta/nixos-app-helpers.nix`; the base bundle still contains other meta contributors (docs, owner, nixpkgs-allowed-unfree), so the helper injection never enters the host evaluation, leaving both `_module.args.nixosRoleHelpers` and the `flake.lib.nixos` helper namespace unset.
+- Adding `modules/meta/nixos-helpers.nix` to import the helper modules ensures `_module.args.nixosRoleHelpers` and `_module.args.nixosAppHelpers` appear in base-only evaluation, and `modules/meta/nixos-roles-import.nix` now pulls `modules/roles/**` into the base aggregator. After those changes `config.flake.nixosModules.roles` finally exposes the first role (`ai-agents`), proving the aggregator is active—but the remaining roles still fail to load because their prerequisites (apps, window-manager modules, etc.) aren’t satisfied during the scaffold run.
+- Evaluating the full System76 stack still strips `_module.args` back to `{ extendModules, moduleType, pkgs }`; `config.home-manager` retains only `backupFileExtension`, `extraAppImports`, `extraSpecialArgs`, `sharedModules`, `useGlobalPkgs`, and `users`, so options like `enableLegacyProfileManagement`, `overwriteBackup`, `useUserPackages`, and `verbose` remain missing.
+- The `_module.args` trace continues to show that the collapse happens at the `pre-system76` checkpoint. Because only one role successfully registers, `modules/system76/imports.nix` still fails to resolve `base` and other workstation roles (the helper falls back to `config.flake.nixosModules.roles`, which lacks those keys), preventing the base bundle—and thus the Home Manager glue—from executing.
+- Instrumenting the scaffold with `debug.roleProbe` now records every role module under `modules/roles`. Most files export a `flake.nixosModules.roles.<name>.imports` attrset and evaluate cleanly, while dotted roles (for example `roles.dev.clj`) land under nested paths that our probe flattens separately. Roles that fan out to language bundles (`dev-clj`, `dev-go`, `dev-py`, `dev-rs`) expect stubs under `flake.nixosModules.lang.*`, and desktop roles reach for `flake.nixosModules.window-manager.i3`. Until those namespaces are stubbed, the aggregator keeps collapsing to just `ai-agents`, so the helpers never expose additional role names to the workstation stack.
+- Added a dedicated `stubModule` to the scaffold that pre-populates `flake.nixosModules.apps`, `flake.nixosModules.lang`, and `flake.nixosModules."window-manager"` with real modules when available and inert lambdas otherwise. This prevents `nixos-app-helpers` and the desktop roles from crashing on missing lookups, but the flattened attrset at `config.flake.nixosModules.roles` still comes back empty—confirming that the roles import itself isn’t materialising yet, even though each role module evaluates successfully in isolation.
+- With `DEBUG_ROLES=1` instrumentation in `modules/meta/nixos-role-helpers.nix`, both the base-only harness and the full System76 evaluation show `flattenRoles` merging the complete key set (`ai-agents`, `base`, `chat`, `cli`, `cloudflare`, `desktop`, `dev`, `file-sharing`, `files`, `gaming`, `media`, `net`, `pentesting-devshell`, `productivity`, `security`, `warp-client`, `xserver`) and `availableRoles` exposing the same list. The helper attrset is therefore intact; the disappearance of `config.flake.nixosModules.roles` happens after the helper runs (or never receives the merged attrset), not because the flatten step discarded anything.
+- The debug stub was the culprit: it previously assigned `config.flake.nixosModules` to a tiny attrset `{ apps, lang, "window-manager" }`, erasing the default `roles` subtree provided by `inputs.self.nixosModules`. Updating the stub to merge against `self.nixosModules` (`lib.mkDefault (selfModules // { ... })`) lets the native flake exports flow through. After the change, `debug.flakeFinal` shows the full namespace and `roles = [ "_file" "imports" ]`, matching the structure the helper already flattened.
+- The System76 host definition also skipped `flake.nixosModules.base`, so the workstation bundle was layering its tweaks onto an empty Home Manager attrset. Adding `getModule "base"` to `modules/system76/imports.nix` ensures the host imports the base bundle before `workstation`. After that change, the full System76 evaluation (`sc.modules`) retains the default flags—`enableLegacyProfileManagement`, `overwriteBackup`, `useUserPackages`, `verbose`—and `config.home-manager` once again matches the base harness.
+- Evaluating the base harness directly with `nix eval --accept-flake-config --impure --show-trace --expr 'let flake = builtins.getFlake (toString ./.); harness = import ./debug/system76-home-manager-scaffold.nix { inherit flake; lib = flake.inputs.nixpkgs.lib; }; lib = flake.inputs.nixpkgs.lib; in lib.evalModules { modules = harness.baseModulesForTrace; specialArgs = harness.specialArgs; }'` still aborts with `error: The option 'flake.nixosModules' does not exist. Definition values: - In '/nix/store/.../modules/roles/xserver.nix'`. This pinpoints the remaining ordering bug: role modules evaluate before any bootstrap path defines the `flake.*` option schema, so base-only evaluation never succeeds.
+- Inspecting `flake.nixosModules.base.imports` shows the synthetic entry for `modules/meta/nixos-helpers.nix` expands to `{ imports = [ /…/nixos-roles-preload.nix /…/flake-output.nix /…/nixos-role-helpers.nix /…/nixos-app-helpers.nix ] }`. Because that list starts with `nixos-roles-preload.nix`, evaluation hits `config.flake.nixosModules = …` before `modules/meta/flake-output.nix` defines the `flake.*` option schema, so the first role that touches it (`roles/xserver.nix`) still throws.
+- Reordering that helper list to run `flake-output.nix` first fixes the immediate ordering issue, but the base scaffold still fails: `lib.evalModules` continues to throw “option 'flake.nixosModules' does not exist” because the harness never loads the flake-parts bootstrap (`flake-parts/modules/nixosModules.nix`). Attempts to stub the option locally (`options.flake.nixosModules = …`) are ignored—the failure trace never shows the stub firing—so we must import the real bootstrap module (with its `mkSubmoduleOptions` wiring) before evaluating any role file.
+- Added `debug/flake-nixosModules-reproducer.nix` to isolate the failure: evaluating a single module that writes `config.flake.nixosModules.roles.xserver` reproduces the missing-option error, while prepending a minimal stub module (`options.flake.nixosModules = …`) lets the same evaluation succeed. This confirms the harness simply needs the option defined before the roles run; the remaining work is ensuring the real bootstrap executes during System76 evaluation instead of relying on ad-hoc stubs.
+- Reintroducing the manual `modules/meta/flake-output.nix` import inside `modules/meta/nixos-helpers.nix` remains necessary today. Without it, the meta aggregator (`nixos-roles-preload` → `nixos-role-helpers` → `nixos-app-helpers`) crashes immediately because no one has defined the `flake.*` option namespace yet. With the import restored, the evaluation makes it past the helpers and fails later in `modules/roles/xserver.nix`, indicating the bootstrap simply moves the symptom downstream rather than fixing the underlying requirement to seed `flake.*` before either stack runs.
+- Reordering the helper list so `flake-output.nix` runs before `nixos-roles-preload.nix` removes that early assignment, but the base harness continues to fail: the structured trace still reports `error: The option 'flake.nixosModules' does not exist` because the harness never imports the flake-level bootstrap emitted by `inputs.import-tree`. In the real flake, `/nix/store/*/modules/nixosModules.nix` registers the option; without that module in the harness, only the role definitions remain, and the lookup still throws.
 
 ## Consequence
 
@@ -29,5 +49,6 @@ A dedicated scaffold (`debug/system76-home-manager-scaffold.nix`) now recreates
 
 ## Next Investigation Steps
 
-1. Extend the scaffold to the base aggregator and pinpoint the exact module under `flake.nixosModules.base` that drops the Home Manager keys.
-2. Once the culprit is identified, decide whether to feed flake inputs there, merge instead of overwrite, or rearrange imports.
+1. Trace exactly where `_module.args.nixosRoleHelpers` is supposed to be injected (the meta helpers module) and confirm whether import-tree skips it or a later module overwrites `_module.args`.
+2. Verify the evaluation context around `modules/workstation.nix` once the helpers are present—ensure `resolveRole "base"` pulls in the glue and that `config.home-manager` retains the full attrset.
+3. Only after helpers flow, revisit the `home-manager.sharedModules` merge conflict to make sure the overlays still compose cleanly and no new regressions appear.
diff --git a/modules/hardware/monitors/lenovo-y27q-20.nix b/modules/hardware/monitors/lenovo-y27q-20.nix
index 1fe94cd3d..28eabaece 100644
--- a/modules/hardware/monitors/lenovo-y27q-20.nix
+++ b/modules/hardware/monitors/lenovo-y27q-20.nix
@@ -201,6 +201,7 @@ let
               serviceConfig = {
                 Type = "oneshot";
                 ExecStart = assignScript;
+                SuccessExitStatus = "0 1";
               };
             };
           }
diff --git a/modules/home-manager/nixos.nix b/modules/home-manager/nixos.nix
index 19b00fe23..b35b9aa8c 100644
--- a/modules/home-manager/nixos.nix
+++ b/modules/home-manager/nixos.nix
@@ -4,7 +4,7 @@
   lib,
   ...
 }:
-{
+builtins.trace "hm.nixos entry" {
   flake.nixosModules = {
     base = {
       imports = [ inputs.home-manager.nixosModules.home-manager ];
@@ -47,7 +47,19 @@
             flakeAttrs = config.flake or { };
             hmModulesFromConfig = lib.attrByPath [ "homeManagerModules" ] { } flakeAttrs;
             hmModulesFromInputs = lib.attrByPath [ "self" "homeManagerModules" ] { } inputsArg;
-            hmModules = if hmModulesFromConfig != { } then hmModulesFromConfig else hmModulesFromInputs;
+            hmModules =
+              let
+                combined =
+                  assert (
+                    lib.hasAttrByPath [ "homeManagerModules" "base" ] flakeAttrs
+                    || lib.hasAttrByPath [ "self" "homeManagerModules" "base" ] inputsArg
+                  );
+                  if hmModulesFromConfig != { } then hmModulesFromConfig else hmModulesFromInputs;
+              in
+              builtins.trace (
+                "hm.nixos hmModules keys: "
+                + (if combined != { } then lib.concatStringsSep ", " (lib.attrNames combined) else "<empty>")
+              ) combined;
             hmApps = hmModules.apps or { };
             hasApp = name: lib.hasAttr name hmApps;
             getApp =
diff --git a/modules/meta/flake-output.nix b/modules/meta/flake-output.nix
index 2fe330d17..36ccb7908 100644
--- a/modules/meta/flake-output.nix
+++ b/modules/meta/flake-output.nix
@@ -64,4 +64,8 @@
       };
     };
   };
+
+  config.flake.lib = lib.mkDefault { };
+  config.flake.homeManagerModules = lib.mkDefault { };
+  config.flake.nixosModules = lib.mkDefault { };
 }
diff --git a/modules/meta/nixos-app-helpers.nix b/modules/meta/nixos-app-helpers.nix
index dfdf90135..d5a94baad 100644
--- a/modules/meta/nixos-app-helpers.nix
+++ b/modules/meta/nixos-app-helpers.nix
@@ -51,11 +51,10 @@ let
 
   appsDir = ../apps;
 
-  baseApps =
-    if lib.hasAttrByPath [ "apps" ] config.flake.nixosModules then
-      flattenApps config.flake.nixosModules.apps
-    else
-      { };
+  nixosModulesAttr =
+    if config ? flake && config.flake ? nixosModules then config.flake.nixosModules else { };
+
+  baseApps = if nixosModulesAttr ? apps then flattenApps nixosModulesAttr.apps else { };
 
   appFiles = builtins.readDir appsDir;
 
diff --git a/modules/meta/nixos-helpers.nix b/modules/meta/nixos-helpers.nix
new file mode 100644
index 000000000..0c1656428
--- /dev/null
+++ b/modules/meta/nixos-helpers.nix
@@ -0,0 +1,8 @@
+_: {
+  flake.nixosModules.base.imports = [
+    ./flake-output.nix
+    ./nixos-roles-preload.nix
+    ./nixos-role-helpers.nix
+    ./nixos-app-helpers.nix
+  ];
+}
diff --git a/modules/meta/nixos-role-helpers.nix b/modules/meta/nixos-role-helpers.nix
index f62352fff..8f5ef777e 100644
--- a/modules/meta/nixos-role-helpers.nix
+++ b/modules/meta/nixos-role-helpers.nix
@@ -5,6 +5,8 @@
   ...
 }:
 let
+  enableTrace = builtins.getEnv "DEBUG_ROLES" == "1";
+  traceValue = msg: value: if enableTrace then builtins.trace msg value else value;
   sanitizeModule =
     module:
     if module == null then
@@ -13,15 +15,20 @@ let
       module
     else if builtins.isAttrs module then
       let
-        cleaned = builtins.removeAttrs module [
-          "_file"
-          "imports"
-          "flake"
-        ];
+        cleaned =
+          let
+            stripped = builtins.removeAttrs module [
+              "_file"
+              "imports"
+            ];
+          in
+          traceValue ("sanitizeModule has flake? " + (if module ? flake then "yes" else "no")) stripped;
         imported = module.imports or [ ];
         sanitizedImports = lib.filter (m: m != null) (map sanitizeModule imported);
       in
-      cleaned
+      traceValue (
+        "sanitizeModule direct keys: " + lib.concatStringsSep ", " (lib.attrNames cleaned)
+      ) cleaned
       // lib.optionalAttrs (sanitizedImports != [ ]) {
         imports = sanitizedImports;
       }
@@ -43,11 +50,24 @@ let
             "imports"
           ])
         ) module;
-        sanitizedDirect = lib.mapAttrs (_: sanitizeModule) direct;
+        sanitizedDirect = lib.mapAttrs (
+          name: value: if name == "flake" then value else sanitizeModule value
+        ) direct;
+        tracedSanitizedDirect =
+          if sanitizedDirect ? flake then
+            traceValue (
+              "flattenRoles preserved flake keys: "
+              + lib.concatStringsSep ", " (lib.attrNames sanitizedDirect.flake)
+            ) sanitizedDirect
+          else
+            sanitizedDirect;
         imported = module.imports or [ ];
         merge = acc: value: acc // flattenRoles value;
+        merged = lib.foldl' merge tracedSanitizedDirect (
+          if builtins.isList imported then imported else [ imported ]
+        );
       in
-      lib.foldl' merge sanitizedDirect (if builtins.isList imported then imported else [ imported ])
+      traceValue ("flattenRoles merged keys: " + lib.concatStringsSep ", " (lib.attrNames merged)) merged
     else
       { };
 
@@ -59,7 +79,12 @@ let
           && config.flake ? nixosModules
           && lib.hasAttrByPath [ "roles" ] config.flake.nixosModules
         then
-          flattenRoles config.flake.nixosModules.roles
+          let
+            roles = flattenRoles config.flake.nixosModules.roles;
+          in
+          traceValue (
+            "availableRoles.fromConfig keys: " + lib.concatStringsSep ", " (lib.attrNames roles)
+          ) roles
         else
           { };
       fromSelf =
@@ -67,11 +92,18 @@ let
           selfModules = (inputs.self.outputs or { }).nixosModules or { };
         in
         if lib.hasAttrByPath [ "roles" ] selfModules then
-          flattenRoles (lib.getAttrFromPath [ "roles" ] selfModules)
+          let
+            roles = flattenRoles (lib.getAttrFromPath [ "roles" ] selfModules);
+          in
+          traceValue (
+            "availableRoles.fromSelf keys: " + lib.concatStringsSep ", " (lib.attrNames roles)
+          ) roles
         else
           { };
     in
-    fromConfig // fromSelf;
+    traceValue (
+      "availableRoles keys: " + lib.concatStringsSep ", " (lib.attrNames (fromConfig // fromSelf))
+    ) (fromConfig // fromSelf);
 
   roleHelpers = rec {
     hasRole = name: builtins.hasAttr name availableRoles;
diff --git a/modules/meta/nixos-roles-import.nix b/modules/meta/nixos-roles-import.nix
new file mode 100644
index 000000000..45903a20e
--- /dev/null
+++ b/modules/meta/nixos-roles-import.nix
@@ -0,0 +1,6 @@
+{ inputs, ... }:
+{
+  flake.nixosModules.base.imports = [
+    (inputs.import-tree ./../roles)
+  ];
+}
diff --git a/modules/meta/nixos-roles-preload.nix b/modules/meta/nixos-roles-preload.nix
new file mode 100644
index 000000000..e2ffa26b4
--- /dev/null
+++ b/modules/meta/nixos-roles-preload.nix
@@ -0,0 +1,19 @@
+{
+  inputs ? { },
+  self ? null,
+  lib,
+  ...
+}:
+let
+  resolvedSelf =
+    if self != null then
+      self
+    else if inputs ? self then
+      inputs.self
+    else
+      builtins.getFlake (toString ../..);
+  modules = resolvedSelf.nixosModules or { };
+in
+{
+  config.flake.nixosModules = lib.mkDefault modules;
+}
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index e52d8cd26..71a0b2c95 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -40,7 +40,15 @@ let
     "chat"
   ];
   workstationModule = getModule "workstation";
-  baseModules = lib.filter (module: module != null) [
+  baseModule = getModule "base";
+  flakeOptionModule = import ../meta/flake-output.nix;
+  flakeInitModule = _: {
+    flake = lib.mkDefault { };
+  };
+  baseModulesRaw = [
+    flakeOptionModule
+    flakeInitModule
+    baseModule
     inputs.nixos-hardware.nixosModules.system76
     inputs.nixos-hardware.nixosModules.system76-darp6
     (getModule "packages")
@@ -51,6 +59,7 @@ let
     (getModule "duplicati-r2")
     (getModule "virt")
   ];
+  baseModules = lib.filter (module: module != null) baseModulesRaw;
   virtualizationModules = lib.filter (module: module != null) (
     map getVirtualizationModule [
       "docker"
@@ -74,7 +83,9 @@ let
 in
 {
   configurations.nixos.system76.module = {
-    _module.check = false;
+    _module.check = true;
+    _module.args.inputs = lib.mkDefault inputs;
+    _module.args.self = lib.mkDefault (inputs.self or null);
     imports =
       baseModules
       ++ virtualizationModules
@@ -101,6 +112,10 @@ in
         )
         config.configurations.nixos.system76.module
       ];
+      specialArgs = {
+        inherit inputs;
+        self = inputs.self or null;
+      };
     };
   };
 }
diff --git a/notes.md b/notes.md
new file mode 100644
index 000000000..2ba423d4a
--- /dev/null
+++ b/notes.md
@@ -0,0 +1,4 @@
+1. Decide how to adapt modules/system76/imports.nix to the import-tree layout—either flatten config.flake.nixosModules
+   before the lookups (e.g. by running inputs.import-tree.flatten once and caching the result) or teach getModule/
+   getRoleModule to read from .content.
+2. Once those lookups succeed, re-run the scaffold (nix eval --impure --accept-flake-config … eval.config.debug.hmTrace)

From edb1219dc0c6944845f99f17131450c430af1d54 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Tue, 21 Oct 2025 18:20:04 +0300
Subject: [PATCH 15/20] do not assign empty values

---
 modules/system76/imports.nix | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index 71a0b2c95..efdb23a72 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -5,8 +5,8 @@
   ...
 }:
 let
-  flake = config.flake or { };
-  nixosModules = flake.nixosModules or { };
+  flake = config.flake; # or { };
+  nixosModules = flake.nixosModules; # or { };
   hasModule = name: lib.hasAttr name nixosModules;
   getModule = name: if hasModule name then lib.getAttr name nixosModules else null;
   roleHelpers =

From 9250ebf5b4fbaae670c42b7cce19cfc0a5c37b55 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Tue, 21 Oct 2025 20:38:10 +0300
Subject: [PATCH 16/20] fix: remove importing of flake-output in system76
 imports

---
 modules/meta/flake-output.nix | 1 +
 modules/system76/imports.nix  | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/modules/meta/flake-output.nix b/modules/meta/flake-output.nix
index 36ccb7908..a63b3c483 100644
--- a/modules/meta/flake-output.nix
+++ b/modules/meta/flake-output.nix
@@ -62,6 +62,7 @@
         default = { };
         description = "Aggregated Home Manager modules with freeform roles";
       };
+
     };
   };
 
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index efdb23a72..ff5b40a96 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -41,12 +41,12 @@ let
   ];
   workstationModule = getModule "workstation";
   baseModule = getModule "base";
-  flakeOptionModule = import ../meta/flake-output.nix;
+  flakeNixosModulesBootstrap = import ./flake-nixosModules-bootstrap.nix;
   flakeInitModule = _: {
     flake = lib.mkDefault { };
   };
   baseModulesRaw = [
-    flakeOptionModule
+    flakeNixosModulesBootstrap
     flakeInitModule
     baseModule
     inputs.nixos-hardware.nixosModules.system76
@@ -115,6 +115,7 @@ in
       specialArgs = {
         inherit inputs;
         self = inputs.self or null;
+        system76NeedsFlakeBootstrap = true;
       };
     };
   };

From e7c7a0560ea92d474abaed6c4b389293f9e52cd5 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Wed, 22 Oct 2025 16:31:44 +0300
Subject: [PATCH 17/20] fails at missing .apps

---
 debug/flake-nixosModules-reproducer.nix       |   15 +-
 debug/system76-home-manager-scaffold.nix      |  173 +-
 docs/flake-parts-docs/SUMMARY.md              |   26 +
 .../best-practices-for-module-writing.md      |   40 +
 docs/flake-parts-docs/cheat-sheet.md          |   60 +
 docs/flake-parts-docs/debug.md                |   77 +
 .../define-custom-flake-attribute.md          |   30 +
 .../define-module-in-separate-file.md         |   93 +
 .../dogfood-a-reusable-module.md              |   99 +
 .../generate-documentation.md                 |   83 +
 docs/flake-parts-docs/getting-started.md      |   48 +
 docs/flake-parts-docs/highlight.js            | 2098 +++++++++++++++++
 docs/flake-parts-docs/intro-continued.md      |    7 +
 docs/flake-parts-docs/module-arguments.md     |  211 ++
 docs/flake-parts-docs/overlays.md             |  109 +
 docs/flake-parts-docs/system.md               |   19 +
 docs/system76-home-manager-observations.md    |   13 +
 flake.nix                                     |   43 +-
 modules/home-manager/nixos.nix                |  160 +-
 modules/meta/nixos-helpers.nix                |    5 +-
 modules/meta/nixos-home-manager-collect.nix   |   31 +
 modules/meta/nixos-roles-import.nix           |    6 -
 modules/meta/nixos-roles-preload.nix          |   19 -
 .../system76/flake-nixosModules-bootstrap.nix |   20 +
 modules/system76/imports.nix                  |  200 +-
 25 files changed, 3530 insertions(+), 155 deletions(-)
 create mode 100644 docs/flake-parts-docs/SUMMARY.md
 create mode 100644 docs/flake-parts-docs/best-practices-for-module-writing.md
 create mode 100644 docs/flake-parts-docs/cheat-sheet.md
 create mode 100644 docs/flake-parts-docs/debug.md
 create mode 100644 docs/flake-parts-docs/define-custom-flake-attribute.md
 create mode 100644 docs/flake-parts-docs/define-module-in-separate-file.md
 create mode 100644 docs/flake-parts-docs/dogfood-a-reusable-module.md
 create mode 100644 docs/flake-parts-docs/generate-documentation.md
 create mode 100644 docs/flake-parts-docs/getting-started.md
 create mode 100644 docs/flake-parts-docs/highlight.js
 create mode 100644 docs/flake-parts-docs/intro-continued.md
 create mode 100644 docs/flake-parts-docs/module-arguments.md
 create mode 100644 docs/flake-parts-docs/overlays.md
 create mode 100644 docs/flake-parts-docs/system.md
 create mode 100644 modules/meta/nixos-home-manager-collect.nix
 delete mode 100644 modules/meta/nixos-roles-import.nix
 delete mode 100644 modules/meta/nixos-roles-preload.nix
 create mode 100644 modules/system76/flake-nixosModules-bootstrap.nix

diff --git a/debug/flake-nixosModules-reproducer.nix b/debug/flake-nixosModules-reproducer.nix
index e32699d19..bc30d43b0 100644
--- a/debug/flake-nixosModules-reproducer.nix
+++ b/debug/flake-nixosModules-reproducer.nix
@@ -4,20 +4,17 @@
 }:
 let
   optionStub =
-    { lib, ... }:
-    {
+    { lib, ... }@args:
+    let
+      useStub = (args ? forceStubBootstrap) && args.forceStubBootstrap;
+    in
+    lib.mkIf useStub {
       options.flake.nixosModules = lib.mkOption {
-        type = lib.types.lazyAttrsOf lib.types.anything;
+        type = lib.types.lazyAttrsOf lib.types.deferredModule;
         default = { };
         description = "Debug stub: defines flake.nixosModules so downstream modules can assign into it.";
       };
-      options.flake.lib = lib.mkOption {
-        type = lib.types.attrsOf lib.types.anything;
-        default = { };
-        description = "Debug stub: allows modules to write helpers under flake.lib.*";
-      };
       config.flake.nixosModules = lib.mkDefault { };
-      config.flake.lib = lib.mkDefault { };
     };
 
   roleModule =
diff --git a/debug/system76-home-manager-scaffold.nix b/debug/system76-home-manager-scaffold.nix
index 7e611e2e2..0e60574db 100644
--- a/debug/system76-home-manager-scaffold.nix
+++ b/debug/system76-home-manager-scaffold.nix
@@ -7,12 +7,20 @@ let
   inherit (flake.nixosConfigurations.system76) _module;
   sourceModulesResult = builtins.tryEval _module.args.modules;
   sourceModules = if sourceModulesResult.success then sourceModulesResult.value else [ ];
-  sourceModulesWithBootstrap = [ optionBootstrapModule ] ++ sourceModules;
+  sourceModulesWithBootstrap = [ flakePartsBootstrapModule ] ++ sourceModules;
   freeform = lib.types.attrsOf lib.types.anything;
   roleDir = ./../modules/roles;
   appsDir = ./../modules/apps;
   langDir = ./../modules/languages;
   windowManagerDir = ./../modules/window-manager;
+  rolesDir = ./../modules/roles;
+  flakePartsModulePath = flake.inputs.flake-parts.outPath + "/modules/nixosModules.nix";
+  flakePartsBootstrapModule = (import flakePartsModulePath) {
+    inherit (flake.inputs.nixpkgs) lib;
+    self = flake;
+    flake-parts-lib = flake.inputs.flake-parts.lib;
+    moduleLocation = flakePartsModulePath;
+  };
   roleNames =
     let
       entries = builtins.readDir roleDir;
@@ -98,6 +106,21 @@ let
 
   windowManagerStubs = lib.genAttrs windowManagerNames mkWindowManagerStub;
 
+  roleEntries = builtins.readDir rolesDir;
+  roleNamesFromFiles = builtins.filter (
+    name: roleEntries.${name} == "regular" && lib.hasSuffix ".nix" name
+  ) (builtins.attrNames roleEntries);
+  roleStubs = lib.genAttrs roleNamesFromFiles (
+    filename:
+    let
+      name = lib.removeSuffix ".nix" filename;
+    in
+    {
+      _file = "stub.roles.${name}";
+      imports = [ (rolesDir + "/${filename}") ];
+    }
+  );
+
   mkNamespaceOption =
     name:
     lib.mkOption {
@@ -106,9 +129,6 @@ let
       description = "${name} scaffold (debug only)";
     };
 
-  optionBootstrapModule =
-    (import ./flake-nixosModules-reproducer.nix { inherit flake lib; }).optionStub;
-
   scaffoldModule =
     { config, lib, ... }:
     let
@@ -122,11 +142,6 @@ let
     in
     {
       options = {
-        flake = lib.mkOption {
-          type = lib.types.submodule { freeformType = freeform; };
-          default = { };
-          description = "Debug stub: start with an empty flake namespace; downstream modules populate nixosModules/lib as needed.";
-        };
         nixpkgs = lib.mkOption {
           type = lib.types.submodule { freeformType = freeform; };
           default = flake.inputs.nixpkgs or { };
@@ -203,6 +218,13 @@ let
         else
           [ ];
       roleMsg = if roleModules == [ ] then "<empty>" else builtins.concatStringsSep ", " roleModules;
+      homeFlakeModules =
+        if config ? flake && config.flake ? homeManagerModules then
+          builtins.attrNames config.flake.homeManagerModules
+        else
+          [ ];
+      homeFlakeMsg =
+        if homeFlakeModules == [ ] then "<empty>" else builtins.concatStringsSep ", " homeFlakeModules;
     in
     {
       config = {
@@ -212,8 +234,15 @@ let
           flakeTrace.${label} = {
             nixosModules = flakeMsg;
             roles = roleMsg;
+            homeManagerModules = homeFlakeMsg;
           };
         };
+        assertions = [
+          {
+            assertion = config ? flake && config.flake ? nixosModules;
+            message = "flake.nixosModules missing after " + label;
+          }
+        ];
       };
     };
 
@@ -229,6 +258,7 @@ let
           apps = (selfModules.apps or { }) // appStubs;
           lang = (selfModules.lang or { }) // langStubs;
           "window-manager" = (selfModules."window-manager" or { }) // windowManagerStubs;
+          roles = (selfModules.roles or { }) // roleStubs;
         }
       );
     };
@@ -252,6 +282,9 @@ let
 
   instrumentImports =
     prefix: modules:
+    let
+      normalized = map toModule modules;
+    in
     lib.concatMap (
       pair:
       let
@@ -261,11 +294,36 @@ let
         annotated
         (mkTraceModule pair.label)
       ]
-    ) (mkPairs prefix modules);
+    ) (mkPairs prefix normalized);
 
   first = builtins.elemAt sourceModulesWithBootstrap 0;
   top = builtins.elemAt sourceModulesWithBootstrap 1;
   last = builtins.elemAt sourceModulesWithBootstrap 2;
+  toModule =
+    module:
+    if builtins.isFunction module then
+      module
+    else if builtins.isAttrs module then
+      if module ? _type && module._type == "order" then
+        toModule module.content
+      else
+        module
+        // {
+          config = module.config or { };
+          options = module.options or { };
+          disabledModules = module.disabledModules or [ ];
+        }
+    else
+      {
+        _file = builtins.toString module;
+        imports = [ module ];
+        config = { };
+        options = { };
+        disabledModules = [ ];
+      };
+  topModule = toModule top;
+  firstModule = toModule first;
+  lastModule = toModule last;
 
   roleProbeModule =
     { config, lib, ... }:
@@ -279,6 +337,7 @@ let
                 if modulesAttr ? content && modulesAttr.content ? roles then modulesAttr.content.roles else { }
               );
             toNames = attr: if attr ? content then builtins.attrNames attr.content else builtins.attrNames attr;
+            homeAttr = config.flake.homeManagerModules or { };
           in
           {
             nixosModules =
@@ -287,11 +346,13 @@ let
               else
                 builtins.attrNames modulesAttr;
             roles = toNames rolesAttr;
+            homeManagerModules = builtins.attrNames homeAttr;
           }
         else
           {
             nixosModules = [ ];
             roles = [ ];
+            homeManagerModules = [ ];
           };
       evalRole =
         name:
@@ -360,35 +421,99 @@ let
 
   interleaved = instrumentImports "system76" imports;
 
-  baseTop = flake.nixosModules.base;
-  baseImports = baseTop.imports;
-  baseImportsWithBootstrap = [ optionBootstrapModule ] ++ baseImports;
+  baseImportsNormalized = map toModule (flake.nixosModules.base.imports or [ ]);
 
-  baseInterleaved = instrumentImports "base" baseImportsWithBootstrap;
+  baseInterleaved = instrumentImports "base" baseImportsNormalized;
 
-  baseModule = baseTop // {
+  baseModule = {
+    _file = "scaffold/baseModule";
     imports = baseInterleaved;
+    config = { };
   };
   baseModulesForTrace = [
     scaffoldModule
+    firstModule
     stubModule
-    first
     baseModule
     roleProbeModule
   ];
   modules = [
     scaffoldModule
     stubModule
-    first
+    firstModule
     (mkTraceModule "pre-system76")
-    (top // { imports = [ optionBootstrapModule ] ++ interleaved; })
-    last
+    (topModule // { imports = interleaved; })
+    lastModule
     roleProbeModule
   ];
   specialArgs = _module.specialArgs // {
     inherit (flake) inputs;
     self = flake;
+    system76NeedsFlakeBootstrap = true;
+    "flake-parts-lib" = flake.inputs.flake-parts.lib;
+    moduleLocation = flakePartsModulePath;
   };
+  prefixHomeManagerTraces =
+    let
+      count = lib.length interleaved;
+      limit = if count < 16 then count else 16;
+      basePrefix = [
+        scaffoldModule
+        stubModule
+        firstModule
+      ];
+      moduleLabel =
+        module:
+        if lib.isAttrs module && module ? label then
+          module.label
+        else if lib.isAttrs module && module ? _file then
+          module._file
+        else if builtins.isFunction module then
+          "<lambda>"
+        else
+          toString module;
+      evaluate =
+        n:
+        let
+          takeAttempt = builtins.tryEval (lib.take n interleaved);
+          prefix = if takeAttempt.success then basePrefix ++ takeAttempt.value else basePrefix;
+          evalAttempt =
+            if takeAttempt.success then
+              builtins.tryEval (
+                lib.evalModules {
+                  modules = prefix;
+                  specialArgs = specialArgs;
+                }
+              )
+            else
+              {
+                success = false;
+                value = takeAttempt.value;
+              };
+        in
+        {
+          step = n;
+          importLabel =
+            if takeAttempt.success then
+              moduleLabel (builtins.elemAt takeAttempt.value (n - 1))
+            else
+              "<take failure>";
+          success = takeAttempt.success && evalAttempt.success;
+          hmKeys =
+            if takeAttempt.success && evalAttempt.success then
+              builtins.attrNames (evalAttempt.value.config.flake.homeManagerModules or { })
+            else
+              [ ];
+          error =
+            if !takeAttempt.success then
+              builtins.toString takeAttempt.value
+            else if !evalAttempt.success then
+              builtins.toString evalAttempt.value
+            else
+              null;
+        };
+    in
+    lib.genList (index: evaluate (index + 1)) limit;
 in
 {
   inherit
@@ -397,6 +522,13 @@ in
     baseModule
     baseModulesForTrace
     scaffoldModule
+    stubModule
+    flakePartsBootstrapModule
+    toModule
+    roleProbeModule
+    firstModule
+    topModule
+    lastModule
     sourceModules
     interleaved
     first
@@ -408,8 +540,7 @@ in
     langNames
     windowManagerNames
     ;
-  inherit optionBootstrapModule;
-  inherit baseImportsWithBootstrap sourceModulesWithBootstrap;
+  inherit baseImportsNormalized sourceModulesWithBootstrap prefixHomeManagerTraces;
   sourceModulesError = if sourceModulesResult.success then null else sourceModulesResult.value;
   sourceModulesSuccess = sourceModulesResult.success;
 }
diff --git a/docs/flake-parts-docs/SUMMARY.md b/docs/flake-parts-docs/SUMMARY.md
new file mode 100644
index 000000000..890cf2758
--- /dev/null
+++ b/docs/flake-parts-docs/SUMMARY.md
@@ -0,0 +1,26 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Getting Started](./getting-started.md)
+- [Cheat Sheet](./cheat-sheet.md)
+- [Tutorials]()
+  - [Best Practices for Module Writing](./best-practices-for-module-writing.md)
+  - [Multi-platform: Working with `system`](./system.md)
+- [Guides]()
+  - [Explore and debug option values](./debug.md)
+  - [Define a Module in a Separate File](./define-module-in-separate-file.md)
+  - [Define Custom Flake Attribute](./define-custom-flake-attribute.md)
+  - [Generate Documentation](./generate-documentation.md)
+  - [Dogfood a Reusable Flake Module](./dogfood-a-reusable-module.md)
+- [Explanation]()
+  - [Overlays](./overlays.md)
+- [Reference Documentation]()
+  - [Module Arguments](./module-arguments.md)
+  - [Options]()
+    - [`flake-parts` (built in)](./options/flake-parts.md)
+      - [`flakeModules`](./options/flake-parts-flakeModules.md)
+      - [`easyOverlay` (warning)](./options/flake-parts-easyOverlay.md)
+      - [`modules`](./options/flake-parts-modules.md)
+      - [`partitions`](./options/flake-parts-partitions.md)
+
+<!-- module list will be concatenated to the end -->
diff --git a/docs/flake-parts-docs/best-practices-for-module-writing.md b/docs/flake-parts-docs/best-practices-for-module-writing.md
new file mode 100644
index 000000000..d3e044f21
--- /dev/null
+++ b/docs/flake-parts-docs/best-practices-for-module-writing.md
@@ -0,0 +1,40 @@
+# Best Practices for Module Writing
+
+Like in NixOS, writing a configuration is quite different from writing a reusable module.
+
+In a configuration, you may take shortcuts which have little impact, but shortcuts in a reusable module lead to surprises for your module's users.
+
+## Do not make assumptions about `inputs`
+
+The inputs are controlled by the user, so your module should make no assumption about which inputs are present.
+This way, the user is free to, for example, bundle up their inputs into a distribution, such as a company platform module.
+
+## Do not traverse `inputs`
+
+By scanning through all the `inputs`, you cause two kinds of problems
+
+- You trigger the fetching of all direct dependencies, even though some may not need to be fetched.
+- You are making an assumption about the role in which an input is used.
+
+By recursing into inputs, you make the problem literally **exponentially** worse:
+
+- Your module logic becomes susceptible to changes deep inside your dependencies' dependencies. Whereas you might have gotten away with an assumption about the role of direct dependencies, making the same assumptions about dependencies and dependencies' dependencies is unlikely to work out well.
+- You trigger the fetching of potentially all transitive dependencies. Instead of a performance inconvenience, we now have a ecosystem-wide scaling problem.
+
+Also note that even if you don't explicitly recurse into the transitive inputs, this behavior still arises if your inputs don't adhere to the rule.
+
+Furthermore it has been observed that lock files can grow indefinitely when mutually dependent flakes don't use `follows` to remove the older version of themselves from the inputs graph.
+
+## Use `perSystem`
+
+When integrating an existing library, it might be easy to add its options in the top level namespace only, as it might already expose a whole-flake interface. However, as most build and test work is done in `perSystem`, users expect to be able to use it in that context. See also [perSystem first (custom flake attribute)](define-custom-flake-attribute.html#persystem-first).
+
+## Bundle with existing flake
+
+Most modules are about some piece of software that it integrates. Ideally the flake module is bundled into the same flake. This simplifies the wiring that users have to do, especially when they want to use a patched version. It's also a bit more efficient as far as fetching is concerned.
+
+## Do not use overly general option names
+
+Most modules will put all their options inside a "namespace" named after their module instead. This way, option path collisions are unlikely to occur.
+
+For example: `perSystem.treefmt.programs`, not `perSystem.programs`.
diff --git a/docs/flake-parts-docs/cheat-sheet.md b/docs/flake-parts-docs/cheat-sheet.md
new file mode 100644
index 000000000..ba4285458
--- /dev/null
+++ b/docs/flake-parts-docs/cheat-sheet.md
@@ -0,0 +1,60 @@
+# Cheat Sheet
+
+Flake-parts offers a couple of ways to access the same thing. This gives you
+freedom to pick the most convenient syntax for a use case.
+
+This page is for you to get a feel for what's what.
+
+## Get a locally defined package
+
+Getting the locally defined `hello` package on/for an `x86_64-linux` host:
+
+### On the command line
+
+```console
+nix build .#hello
+```
+
+### In `perSystem`
+
+```nix
+config.packages.hello
+```
+
+```nix
+self'.packages.hello
+```
+
+The [`self'`](module-arguments.html#self) parameter is derived from the flake `self`, which may benefit from evaluation caching in the future.
+
+The `config` parameter is conceptually simpler and lets you access all options inside `perSystem`, including unexposed ones if you're into defining such options.
+
+### In the top level
+
+> **Note**
+>
+> Anything you can do at the top level, you can do in `perSystem` as well, although you may have to `@` match those module arguments.
+>
+> For example, change the top level function header to e.g. `toplevel@{ config, ... }: /*...*/` so you can access `toplevel.config` despite plain `config` being shadowed by `perSystem = { config, ... }: /*...*/`.
+
+Examples:
+
+```nix
+(getSystem "x86_64-linux").packages.hello
+```
+
+```nix
+withSystem "x86_64-linux" ({ config, ... }:
+  config.packages.hello
+)
+```
+
+```nix
+self.x86_64-linux.packages.hello
+```
+
+```nix
+allSystems.x86_64-linux.packages.hello
+```
+
+`allSystems` may not be future proof if Nix starts to allow building for all systems. An opened up system is incompatible with enumerated systems as required by an attribute set.
diff --git a/docs/flake-parts-docs/debug.md b/docs/flake-parts-docs/debug.md
new file mode 100644
index 000000000..f3d80c916
--- /dev/null
+++ b/docs/flake-parts-docs/debug.md
@@ -0,0 +1,77 @@
+# Explore and debug option values
+
+Sometimes the public interface of a flake is not enough. To inspect all option values, you can enable [`debug`](options/flake-parts.html#opt-debug) and explore otherwise private values with the repl.
+
+## Start debugging
+
+1.  Add `debug = true;`
+    Example:
+
+    ```nix
+    {
+      debug = true;
+
+      systems = /* ... */;
+      perSystem = /* ... */;
+    }
+    ```
+
+2.  Load the flake
+
+    ```
+    $ nix repl
+    nix-repl> :lf .
+
+    ```
+
+## Inspect the perSystem configuration for your machine
+
+```
+nix-repl> currentSystem.allModuleArgs.pkgs.stdenv.hostPlatform.system
+"x86_64-linux"
+
+```
+
+## Inspect the perSystem configuration for a different system type
+
+```
+nix-repl> debug.allSystems.armv7l-linux.allModuleArgs.pkgs.stdenv.hostPlatform.system
+"armv7l-linux"
+
+```
+
+## Inspect a top level option
+
+```
+nix-repl> debug.systems
+[ "x86_64-linux" "aarch64-darwin" ]
+
+```
+
+## Where is a per system value defined?
+
+```
+nix-repl> currentSystem.options.pre-commit.settings.files
+[ "/nix/store/pqp5kwdihyyymfnqq9sk9jsm9xw2lw6s-source/dev-module.nix, via option perSystem" "/nix/store/4wl7k0dp7cjyc4nxy5cm9wdb8jshlg0j-source/flake-module.nix" ]
+
+```
+
+## Where is a top level value defined?
+
+```
+nix-repl> debug.options.system.files
+[ "/nix/store/3na6c6mmyw2yf5chzwwwrp54b8yf96ry-source/flake.nix" ]
+
+```
+
+## Where is a top level option declared?
+
+```
+nix-repl> debug.options.systems.declarations
+[ "/nix/store/3na6c6mmyw2yf5chzwwwrp54b8yf96ry-source/modules/perSystem.nix" ]
+
+```
+
+## See also
+
+- The [`debug` option](options/flake-parts.html#opt-debug) reference.
diff --git a/docs/flake-parts-docs/define-custom-flake-attribute.md b/docs/flake-parts-docs/define-custom-flake-attribute.md
new file mode 100644
index 000000000..463a34e77
--- /dev/null
+++ b/docs/flake-parts-docs/define-custom-flake-attribute.md
@@ -0,0 +1,30 @@
+# Defining a custom flake output attribute
+
+## When should I declare a custom flake output?
+
+With flakes, most of the time, you can use the attribute names suggested by the Nix CLI, NixOS, etc, which already have options in flake-parts, or existing modules you can import.
+
+However, if you're doing something that doesn't fit those labels, you may consider adding a custom attribute to the flake outputs. Your custom attribute may not be easy to use with the existing tools, but that may be expected, if you're writing a new tool or something else that's novel.
+
+## How do I do it?
+
+If your custom output attribute is a one-off because you need to do something special in a single project, all you have to do is define a value in the [`flake` option](options/flake-parts.html#opt-flake).
+
+However, if you want it to be reusable and integrate well, you should declare an option for it, and you could perhaps provide a bit of support logic if that makes sense to do.
+
+## `perSystem` first
+
+<!-- TODO: expand this to stand alone examples and explain it better. -->
+
+Integrating with `perSystem` is highly recommended, because that's where users expect things like packages to be defined. You can bring things that are defined in `perSystem` to the flake outputs in the same way [`packages.nix`](https://github.com/hercules-ci/flake-parts/blob/main/modules/packages.nix) does it.
+
+If your application doesn't follow the same pattern, but you want users to define things in [`perSystem`](options/flake-parts.html#opt-perSystem), you may read the top level `config.allSystems` (internal) option. You can read it in the definition for a new option in the [`flake`](options/flake-parts.html#opt-flake) submodule so that its value is added to the flake outputs.
+
+## `config.flake`
+
+[flake](options/flake-parts.html#opt-flake) is an RFC42-style module, which means that it both has options and it allows arbitrary attributes to be defined in the config, without having to declare an option first.
+Declaring an option is recommended though, for the purposes of documentation, type checking, and allowing multiple config definitions to be merged into a single output value, if applicable.
+
+## Get Help
+
+This is an advanced use case. Feel free to ask questions in [#hercules-ci:matrix.org](https://matrix.to/#/#hercules-ci:matrix.org).
diff --git a/docs/flake-parts-docs/define-module-in-separate-file.md b/docs/flake-parts-docs/define-module-in-separate-file.md
new file mode 100644
index 000000000..4adab23be
--- /dev/null
+++ b/docs/flake-parts-docs/define-module-in-separate-file.md
@@ -0,0 +1,93 @@
+# Define a Module in a Separate File
+
+To avoid writing huge files, you'll want to separate some logic into modules.
+
+When you do so, you'll notice that you've cut access to the lexical scope. You can't access any of the variables in `flake.nix` anymore.
+
+This problem has two possible solutions.
+
+## Factor it out
+
+In short, write an inline module in `flake.nix` (or in a flake module), that `imports` the separate module file and also forms a bridge between the `flake.nix` scope and the option values. This way the majority of the module can be in a separate file.
+
+In the separate file, replace all variables that would come from the lexical scope by new options and reference those through `config`. In `flake.nix` fill in the missing defaults.
+
+Example:
+
+`nixos-module.nix`
+
+```nix
+{ lib, config, ... }: {
+  options = {
+    services.foo = {
+      package = mkOption {
+        defaultText = lib.literalMD "`packages.default` from the foo flake";
+      };
+    };
+  };
+  config = ...;
+}
+```
+
+Flake module:
+
+```nix
+{ withSystem, ... }: {
+  flake.nixosModules.default = { pkgs, ... }: {
+    imports = [ ./nixos-module.nix ];
+    services.foo.package = withSystem pkgs.stdenv.hostPlatform.system ({ config, ... }:
+      config.packages.default
+    );
+  };
+}
+```
+
+For your module users' overriding needs, it's best to make the options as specific as possible; e.g. not a `foo.flake` option, but `foo.package`.
+You'll find that most modules only need one or two such options.
+
+## `importApply`
+
+The `importApply` function can pass extra variables to a module to import.
+
+Instead of loading a file containing a module, it loads a file containing _a function to_ a module, and applies it.
+
+`nixos-module.nix`
+
+```nix
+{ localFlake, withSystem }:
+{
+  lib,
+  config,
+  pkgs,
+  ...
+}:
+{
+  options = {
+    services.foo = {
+      package = mkOption {
+        default = withSystem pkgs.stdenv.hostPlatform.system (
+          { config, ... }: config.packages.default
+        );
+        defaultText = lib.literalMD "`packages.default` from the foo flake";
+      };
+    };
+  };
+  config = ... use localFlake ...;
+}
+```
+
+Flake module:
+
+```nix
+{ flake-parts-lib, self, withSystem, ... }:
+let
+  inherit (flake-parts-lib) importApply;
+in
+{
+  flake.nixosModules.default = importApply ./nixos-module.nix { localFlake = self; inherit withSystem; };
+}
+```
+
+## See Also
+
+- [Dogfooding a Reusable Flake Module](dogfood-a-reusable-module.md), which helps avoid an infinite recursion.
diff --git a/docs/flake-parts-docs/dogfood-a-reusable-module.md b/docs/flake-parts-docs/dogfood-a-reusable-module.md
new file mode 100644
index 000000000..14b6391de
--- /dev/null
+++ b/docs/flake-parts-docs/dogfood-a-reusable-module.md
@@ -0,0 +1,99 @@
+# Dogfood a Reusable Module
+
+_to dogfood: test one's own product by using it for your own purposes_
+
+You can distribute reusable module logic through flakes using flake attributes, and that includes [`flakeModules`](options/flake-parts-flakeModules.html#opt-flake.flakeModules).
+However, importing from `self` is not possible, because such an import could affect the `self` attribute set.
+To use your own exported module, you have to reference it directly.
+
+```
+┌─────────┐   ┌───────────────────────────────────┐
+│ imports │   │ config.flake.flakeModules.default │
+└─────┬───┘   └─────────────────┬─────────────────┘
+      │                         │
+      │      ┌──────────────────┘
+      │      │
+┌─────▼──────▼─────┐
+│ flake-module.nix │
+└──────────────────┘
+```
+
+If your module does not need anything from the local flake's lexical scope, you might implement the references in the diagram above.
+But if you do need to reference, say, a package from your local flake, then you need to apply one of the solutions from [Define a Module in a Separate File](define-module-in-separate-file.md).
+Instead of the arrows joining at the file name, we'll need a `let` binding.
+
+```
+┌─────────┐   ┌───────────────────────────────────┐
+│ imports │   │ config.flake.flakeModules.default │
+└─────┬───┘   └─────────────────┬─────────────────┘
+      │                         │
+      │       ┌─────────────────┘
+      │       │
+┌─────▼───────▼─────────┐
+│ let flakeModule = ... │
+└─────────┬─────────────┘
+          │
+          │
+          │
+┌─────────▼────────┐
+│ flake-module.nix │
+└──────────────────┘
+```
+
+## Example with `importApply`
+
+Here's an example of how this looks using the [`importApply` technique](define-module-in-separate-file.md#importapply).
+This flake shows how to export a flake module that references its own flake, instead of just the user's flake (which would be available in the module arguments).
+The example only demonstrates the principle, by reexporting a locally defined package in the user's flake.
+
+`flake.nix`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } ({ withSystem, flake-parts-lib, ... }:
+    let
+      inherit (flake-parts-lib) importApply;
+      flakeModules.default = importApply ./flake-module.nix { inherit withSystem; };
+    in
+    {
+      imports = [
+        flakeModules.default
+        # inputs.foo.flakeModules.default
+      ];
+      systems = [ "x86_64-linux" "aarch64-darwin" ];
+      perSystem = { pkgs, ... }: {
+        packages.default = pkgs.hello;
+      };
+      flake = {
+        inherit flakeModules;
+      };
+    });
+}
+```
+
+`flake-module.nix`:
+
+```nix
+# The importApply argument. Use this to reference things defined locally,
+# as opposed to the flake where this is imported.
+localFlake:
+
+# Regular module arguments; self, inputs, etc all reference the final user flake,
+# where this module was imported.
+{ lib, config, self, inputs, ... }:
+{
+  perSystem = { system, ... }: {
+    # A copy of hello that was defined by this flake, not the user's flake.
+    packages.greeter = localFlake.withSystem system ({ config, ... }:
+      config.packages.default
+    );
+  };
+}
+```
+
+The ["Factor it out" technique](define-module-in-separate-file.md#factor-it-out) is equally applicable; replace `importApply` by an inline module.
diff --git a/docs/flake-parts-docs/generate-documentation.md b/docs/flake-parts-docs/generate-documentation.md
new file mode 100644
index 000000000..d6b0a1b78
--- /dev/null
+++ b/docs/flake-parts-docs/generate-documentation.md
@@ -0,0 +1,83 @@
+# Generate Documentation
+
+The module system supports the generation of documentation.
+This guide shows how to avoid common solutions to documentation errors, and how to publish documentation here on [flake.parts](https://flake.parts).
+
+## Add `description` to all options
+
+Make sure all options have a `description` or if necessary mark them as `internal = true;`.
+
+## Make sure non-trivial defaults have `defaultText`
+
+Documentation generation works by evaluating your module in a slightly different way, just to extract documentation, while some of the option values are not valid.
+This particularly affects `default` in your `mkOption` calls. Consider the following example:
+
+```nix
+contents = mkOption {
+  description = ''
+    A derivation that produces the contents.
+  '';
+  # no default
+};
+publishPath = mkOption {
+  description = ''
+    The contents to publish.
+  '';
+  default = config.contents;
+};
+```
+
+In this situation, the documentation for `publishPath` requires that we evaluate `contents`, which is unset and therefore results in an error.
+The solution is to add `defaultText`:
+
+```nix
+publishPath = mkOption {
+  description = ''
+    The contents to publish.
+  '';
+  default = config.contents;
+  defaultText = lib.literalExpression "contents";
+  # Alternatively, if you don't want to put non-trivial code here, use markdown:
+  # defaultText = lib.literalMD "the value of the `contents` option";
+};
+```
+
+## Make sure to use `mkPerSystemOption`
+
+While it is possible to declare options using `config.perSystem`, or just `perSystem = { ... }: { options = /* ... */; }`, these modules will not be picked up by the documentation generation.
+
+As a rule of thumb, the documentation generator only traverses through `options` and not through `config`.
+
+To make docs available, use this syntax:
+
+```nix
+{ lib, self, ... }:
+{
+  options.perSystem = flake-parts-lib.mkPerSystemOption ({ config, ... }: {
+    /* ... put perSystem module body here ... */
+  });
+}
+```
+
+## Publish on flake.parts
+
+1. Check that you've added a license to the project. <details><blockquote>Without a license attached, people will be able to look at it, and fork it (because both of that is allowed via GitHub's own Terms of Service), but they may not use it in their own projects, modify it or otherwise do anything else with it. You alone have the exclusive copyright.</blockquote><br/> &mdash; [GitHub Guide on Open Source Licensing](https://github.com/readme/guides/open-source-licensing) </details>
+1. Clone `https://github.com/hercules-ci/flake.parts-website`, or for via ssh: `git@github.com:hercules-ci/flake.parts-website`
+1. Add your flake to the `inputs` in `flake.nix`
+1. Define the details in `render.inputs` in `flake.nix`.
+   See [flake.parts-website reference docs](options/flake.parts-website.md) for option details.
+1. `nix build -L --show-trace`
+1. Open a pull request
+
+## Get help
+
+If you're still getting an error, or a bad output, consider opening a draft PR.
+
+## Private documentation
+
+The `flake.parts-website` flake exposes modules for reuse in your own flake, and could be used to internally publish documentation for private modules.
+These modules are subject to change, but also slow moving.
+
+```console
+$ nix flake init -t flake.parts-website#private-site
+```
diff --git a/docs/flake-parts-docs/getting-started.md b/docs/flake-parts-docs/getting-started.md
new file mode 100644
index 000000000..7c7fe6490
--- /dev/null
+++ b/docs/flake-parts-docs/getting-started.md
@@ -0,0 +1,48 @@
+# Getting Started
+
+## New flake
+
+If your project does not have a flake yet:
+
+```console
+nix flake init -t github:hercules-ci/flake-parts
+```
+
+## Existing flake
+
+Otherwise, add the input,
+
+```nix
+flake-parts.url = "github:hercules-ci/flake-parts";
+```
+
+then slide `mkFlake` between your outputs function head and body,
+
+```nix
+outputs = inputs@{ flake-parts, ... }:
+  # https://flake.parts/module-arguments.html
+  flake-parts.lib.mkFlake { inherit inputs; } (top@{ config, withSystem, moduleWithSystem, ... }: {
+    imports = [
+      # Optional: use external flake logic, e.g.
+      # inputs.foo.flakeModules.default
+    ];
+    flake = {
+      # Put your original flake attributes here.
+    };
+    systems = [
+      # systems for which you want to build the `perSystem` attributes
+      "x86_64-linux"
+      # ...
+    ];
+    perSystem = { config, pkgs, ... }: {
+      # Recommended: move all package definitions here.
+      # e.g. (assuming you have a nixpkgs input)
+      # packages.foo = pkgs.callPackage ./foo/package.nix { };
+      # packages.bar = pkgs.callPackage ./bar/package.nix {
+      #   foo = config.packages.foo;
+      # };
+    };
+  });
+```
+
+Now you can start using the flake-parts options.
diff --git a/docs/flake-parts-docs/highlight.js b/docs/flake-parts-docs/highlight.js
new file mode 100644
index 000000000..0d0098332
--- /dev/null
+++ b/docs/flake-parts-docs/highlight.js
@@ -0,0 +1,2098 @@
+/*
+  Highlight.js 10.1.2 (edd73d24)
+  License: BSD-3-Clause
+  Copyright (c) 2006-2020, Ivan Sagalaev
+*/
+var hljs = (function () {
+  "use strict";
+  function e(n) {
+    Object.freeze(n);
+    var t = "function" == typeof n;
+    return (
+      Object.getOwnPropertyNames(n).forEach(function (r) {
+        !Object.hasOwnProperty.call(n, r) ||
+          null === n[r] ||
+          ("object" != typeof n[r] && "function" != typeof n[r]) ||
+          (t && ("caller" === r || "callee" === r || "arguments" === r)) ||
+          Object.isFrozen(n[r]) ||
+          e(n[r]);
+      }),
+      n
+    );
+  }
+  class n {
+    constructor(e) {
+      (void 0 === e.data && (e.data = {}), (this.data = e.data));
+    }
+    ignoreMatch() {
+      this.ignore = !0;
+    }
+  }
+  function t(e) {
+    return e
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#x27;");
+  }
+  function r(e, ...n) {
+    var t = {};
+    for (const n in e) t[n] = e[n];
+    return (
+      n.forEach(function (e) {
+        for (const n in e) t[n] = e[n];
+      }),
+      t
+    );
+  }
+  function a(e) {
+    return e.nodeName.toLowerCase();
+  }
+  var i = Object.freeze({
+    __proto__: null,
+    escapeHTML: t,
+    inherit: r,
+    nodeStream: function (e) {
+      var n = [];
+      return (
+        (function e(t, r) {
+          for (var i = t.firstChild; i; i = i.nextSibling)
+            3 === i.nodeType
+              ? (r += i.nodeValue.length)
+              : 1 === i.nodeType &&
+                (n.push({ event: "start", offset: r, node: i }),
+                (r = e(i, r)),
+                a(i).match(/br|hr|img|input/) ||
+                  n.push({ event: "stop", offset: r, node: i }));
+          return r;
+        })(e, 0),
+        n
+      );
+    },
+    mergeStreams: function (e, n, r) {
+      var i = 0,
+        s = "",
+        o = [];
+      function l() {
+        return e.length && n.length
+          ? e[0].offset !== n[0].offset
+            ? e[0].offset < n[0].offset
+              ? e
+              : n
+            : "start" === n[0].event
+              ? e
+              : n
+          : e.length
+            ? e
+            : n;
+      }
+      function c(e) {
+        s +=
+          "<" +
+          a(e) +
+          [].map
+            .call(e.attributes, function (e) {
+              return " " + e.nodeName + '="' + t(e.value) + '"';
+            })
+            .join("") +
+          ">";
+      }
+      function u(e) {
+        s += "</" + a(e) + ">";
+      }
+      function d(e) {
+        ("start" === e.event ? c : u)(e.node);
+      }
+      for (; e.length || n.length; ) {
+        var g = l();
+        if (
+          ((s += t(r.substring(i, g[0].offset))), (i = g[0].offset), g === e)
+        ) {
+          o.reverse().forEach(u);
+          do {
+            (d(g.splice(0, 1)[0]), (g = l()));
+          } while (g === e && g.length && g[0].offset === i);
+          o.reverse().forEach(c);
+        } else
+          ("start" === g[0].event ? o.push(g[0].node) : o.pop(),
+            d(g.splice(0, 1)[0]));
+      }
+      return s + t(r.substr(i));
+    },
+  });
+  const s = "</span>",
+    o = (e) => !!e.kind;
+  class l {
+    constructor(e, n) {
+      ((this.buffer = ""), (this.classPrefix = n.classPrefix), e.walk(this));
+    }
+    addText(e) {
+      this.buffer += t(e);
+    }
+    openNode(e) {
+      if (!o(e)) return;
+      let n = e.kind;
+      (e.sublanguage || (n = `${this.classPrefix}${n}`), this.span(n));
+    }
+    closeNode(e) {
+      o(e) && (this.buffer += s);
+    }
+    value() {
+      return this.buffer;
+    }
+    span(e) {
+      this.buffer += `<span class="${e}">`;
+    }
+  }
+  class c {
+    constructor() {
+      ((this.rootNode = { children: [] }), (this.stack = [this.rootNode]));
+    }
+    get top() {
+      return this.stack[this.stack.length - 1];
+    }
+    get root() {
+      return this.rootNode;
+    }
+    add(e) {
+      this.top.children.push(e);
+    }
+    openNode(e) {
+      const n = { kind: e, children: [] };
+      (this.add(n), this.stack.push(n));
+    }
+    closeNode() {
+      if (this.stack.length > 1) return this.stack.pop();
+    }
+    closeAllNodes() {
+      for (; this.closeNode(); );
+    }
+    toJSON() {
+      return JSON.stringify(this.rootNode, null, 4);
+    }
+    walk(e) {
+      return this.constructor._walk(e, this.rootNode);
+    }
+    static _walk(e, n) {
+      return (
+        "string" == typeof n
+          ? e.addText(n)
+          : n.children &&
+            (e.openNode(n),
+            n.children.forEach((n) => this._walk(e, n)),
+            e.closeNode(n)),
+        e
+      );
+    }
+    static _collapse(e) {
+      "string" != typeof e &&
+        e.children &&
+        (e.children.every((e) => "string" == typeof e)
+          ? (e.children = [e.children.join("")])
+          : e.children.forEach((e) => {
+              c._collapse(e);
+            }));
+    }
+  }
+  class u extends c {
+    constructor(e) {
+      (super(), (this.options = e));
+    }
+    addKeyword(e, n) {
+      "" !== e && (this.openNode(n), this.addText(e), this.closeNode());
+    }
+    addText(e) {
+      "" !== e && this.add(e);
+    }
+    addSublanguage(e, n) {
+      const t = e.root;
+      ((t.kind = n), (t.sublanguage = !0), this.add(t));
+    }
+    toHTML() {
+      return new l(this, this.options).value();
+    }
+    finalize() {
+      return !0;
+    }
+  }
+  function d(e) {
+    return e ? ("string" == typeof e ? e : e.source) : null;
+  }
+  const g =
+      "(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",
+    h = { begin: "\\\\[\\s\\S]", relevance: 0 },
+    f = {
+      className: "string",
+      begin: "'",
+      end: "'",
+      illegal: "\\n",
+      contains: [h],
+    },
+    p = {
+      className: "string",
+      begin: '"',
+      end: '"',
+      illegal: "\\n",
+      contains: [h],
+    },
+    b = {
+      begin:
+        /\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/,
+    },
+    m = function (e, n, t = {}) {
+      var a = r({ className: "comment", begin: e, end: n, contains: [] }, t);
+      return (
+        a.contains.push(b),
+        a.contains.push({
+          className: "doctag",
+          begin: "(?:TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):",
+          relevance: 0,
+        }),
+        a
+      );
+    },
+    v = m("//", "$"),
+    x = m("/\\*", "\\*/"),
+    E = m("#", "$");
+  var _ = Object.freeze({
+      __proto__: null,
+      IDENT_RE: "[a-zA-Z]\\w*",
+      UNDERSCORE_IDENT_RE: "[a-zA-Z_]\\w*",
+      NUMBER_RE: "\\b\\d+(\\.\\d+)?",
+      C_NUMBER_RE: g,
+      BINARY_NUMBER_RE: "\\b(0b[01]+)",
+      RE_STARTERS_RE:
+        "!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~",
+      SHEBANG: (e = {}) => {
+        const n = /^#![ ]*\//;
+        return (
+          e.binary &&
+            (e.begin = (function (...e) {
+              return e.map((e) => d(e)).join("");
+            })(n, /.*\b/, e.binary, /\b.*/)),
+          r(
+            {
+              className: "meta",
+              begin: n,
+              end: /$/,
+              relevance: 0,
+              "on:begin": (e, n) => {
+                0 !== e.index && n.ignoreMatch();
+              },
+            },
+            e,
+          )
+        );
+      },
+      BACKSLASH_ESCAPE: h,
+      APOS_STRING_MODE: f,
+      QUOTE_STRING_MODE: p,
+      PHRASAL_WORDS_MODE: b,
+      COMMENT: m,
+      C_LINE_COMMENT_MODE: v,
+      C_BLOCK_COMMENT_MODE: x,
+      HASH_COMMENT_MODE: E,
+      NUMBER_MODE: {
+        className: "number",
+        begin: "\\b\\d+(\\.\\d+)?",
+        relevance: 0,
+      },
+      C_NUMBER_MODE: { className: "number", begin: g, relevance: 0 },
+      BINARY_NUMBER_MODE: {
+        className: "number",
+        begin: "\\b(0b[01]+)",
+        relevance: 0,
+      },
+      CSS_NUMBER_MODE: {
+        className: "number",
+        begin:
+          "\\b\\d+(\\.\\d+)?(%|em|ex|ch|rem|vw|vh|vmin|vmax|cm|mm|in|pt|pc|px|deg|grad|rad|turn|s|ms|Hz|kHz|dpi|dpcm|dppx)?",
+        relevance: 0,
+      },
+      REGEXP_MODE: {
+        begin: /(?=\/[^/\n]*\/)/,
+        contains: [
+          {
+            className: "regexp",
+            begin: /\//,
+            end: /\/[gimuy]*/,
+            illegal: /\n/,
+            contains: [
+              h,
+              { begin: /\[/, end: /\]/, relevance: 0, contains: [h] },
+            ],
+          },
+        ],
+      },
+      TITLE_MODE: { className: "title", begin: "[a-zA-Z]\\w*", relevance: 0 },
+      UNDERSCORE_TITLE_MODE: {
+        className: "title",
+        begin: "[a-zA-Z_]\\w*",
+        relevance: 0,
+      },
+      METHOD_GUARD: { begin: "\\.\\s*[a-zA-Z_]\\w*", relevance: 0 },
+      END_SAME_AS_BEGIN: function (e) {
+        return Object.assign(e, {
+          "on:begin": (e, n) => {
+            n.data._beginMatch = e[1];
+          },
+          "on:end": (e, n) => {
+            n.data._beginMatch !== e[1] && n.ignoreMatch();
+          },
+        });
+      },
+    }),
+    N = "of and for in not or if then".split(" ");
+  function w(e, n) {
+    return n
+      ? +n
+      : (function (e) {
+            return N.includes(e.toLowerCase());
+          })(e)
+        ? 0
+        : 1;
+  }
+  const R = t,
+    y = r,
+    { nodeStream: O, mergeStreams: k } = i,
+    M = Symbol("nomatch");
+  return (function (t) {
+    var a = [],
+      i = Object.create(null),
+      s = Object.create(null),
+      o = [],
+      l = !0,
+      c = /(^(<[^>]+>|\t|)+|\n)/gm,
+      g =
+        "Could not find the language '{}', did you forget to load/include a language module?";
+    const h = { disableAutodetect: !0, name: "Plain text", contains: [] };
+    var f = {
+      noHighlightRe: /^(no-?highlight)$/i,
+      languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i,
+      classPrefix: "hljs-",
+      tabReplace: null,
+      useBR: !1,
+      languages: null,
+      __emitter: u,
+    };
+    function p(e) {
+      return f.noHighlightRe.test(e);
+    }
+    function b(e, n, t, r) {
+      var a = { code: n, language: e };
+      S("before:highlight", a);
+      var i = a.result ? a.result : m(a.language, a.code, t, r);
+      return ((i.code = a.code), S("after:highlight", i), i);
+    }
+    function m(e, t, a, s) {
+      var o = t;
+      function c(e, n) {
+        var t = E.case_insensitive ? n[0].toLowerCase() : n[0];
+        return (
+          Object.prototype.hasOwnProperty.call(e.keywords, t) && e.keywords[t]
+        );
+      }
+      function u() {
+        (null != y.subLanguage
+          ? (function () {
+              if ("" !== A) {
+                var e = null;
+                if ("string" == typeof y.subLanguage) {
+                  if (!i[y.subLanguage]) return void k.addText(A);
+                  ((e = m(y.subLanguage, A, !0, O[y.subLanguage])),
+                    (O[y.subLanguage] = e.top));
+                } else e = v(A, y.subLanguage.length ? y.subLanguage : null);
+                (y.relevance > 0 && (I += e.relevance),
+                  k.addSublanguage(e.emitter, e.language));
+              }
+            })()
+          : (function () {
+              if (!y.keywords) return void k.addText(A);
+              let e = 0;
+              y.keywordPatternRe.lastIndex = 0;
+              let n = y.keywordPatternRe.exec(A),
+                t = "";
+              for (; n; ) {
+                t += A.substring(e, n.index);
+                const r = c(y, n);
+                if (r) {
+                  const [e, a] = r;
+                  (k.addText(t), (t = ""), (I += a), k.addKeyword(n[0], e));
+                } else t += n[0];
+                ((e = y.keywordPatternRe.lastIndex),
+                  (n = y.keywordPatternRe.exec(A)));
+              }
+              ((t += A.substr(e)), k.addText(t));
+            })(),
+          (A = ""));
+      }
+      function h(e) {
+        return (
+          e.className && k.openNode(e.className),
+          (y = Object.create(e, { parent: { value: y } }))
+        );
+      }
+      function p(e) {
+        return 0 === y.matcher.regexIndex ? ((A += e[0]), 1) : ((L = !0), 0);
+      }
+      var b = {};
+      function x(t, r) {
+        var i = r && r[0];
+        if (((A += t), null == i)) return (u(), 0);
+        if (
+          "begin" === b.type &&
+          "end" === r.type &&
+          b.index === r.index &&
+          "" === i
+        ) {
+          if (((A += o.slice(r.index, r.index + 1)), !l)) {
+            const n = Error("0 width match regex");
+            throw ((n.languageName = e), (n.badRule = b.rule), n);
+          }
+          return 1;
+        }
+        if (((b = r), "begin" === r.type))
+          return (function (e) {
+            var t = e[0],
+              r = e.rule;
+            const a = new n(r),
+              i = [r.__beforeBegin, r["on:begin"]];
+            for (const n of i) if (n && (n(e, a), a.ignore)) return p(t);
+            return (
+              r &&
+                r.endSameAsBegin &&
+                (r.endRe = RegExp(
+                  t.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&"),
+                  "m",
+                )),
+              r.skip
+                ? (A += t)
+                : (r.excludeBegin && (A += t),
+                  u(),
+                  r.returnBegin || r.excludeBegin || (A = t)),
+              h(r),
+              r.returnBegin ? 0 : t.length
+            );
+          })(r);
+        if ("illegal" === r.type && !a) {
+          const e = Error(
+            'Illegal lexeme "' +
+              i +
+              '" for mode "' +
+              (y.className || "<unnamed>") +
+              '"',
+          );
+          throw ((e.mode = y), e);
+        }
+        if ("end" === r.type) {
+          var s = (function (e) {
+            var t = e[0],
+              r = o.substr(e.index),
+              a = (function e(t, r, a) {
+                let i = (function (e, n) {
+                  var t = e && e.exec(n);
+                  return t && 0 === t.index;
+                })(t.endRe, a);
+                if (i) {
+                  if (t["on:end"]) {
+                    const e = new n(t);
+                    (t["on:end"](r, e), e.ignore && (i = !1));
+                  }
+                  if (i) {
+                    for (; t.endsParent && t.parent; ) t = t.parent;
+                    return t;
+                  }
+                }
+                if (t.endsWithParent) return e(t.parent, r, a);
+              })(y, e, r);
+            if (!a) return M;
+            var i = y;
+            i.skip
+              ? (A += t)
+              : (i.returnEnd || i.excludeEnd || (A += t),
+                u(),
+                i.excludeEnd && (A = t));
+            do {
+              (y.className && k.closeNode(),
+                y.skip || y.subLanguage || (I += y.relevance),
+                (y = y.parent));
+            } while (y !== a.parent);
+            return (
+              a.starts &&
+                (a.endSameAsBegin && (a.starts.endRe = a.endRe), h(a.starts)),
+              i.returnEnd ? 0 : t.length
+            );
+          })(r);
+          if (s !== M) return s;
+        }
+        if ("illegal" === r.type && "" === i) return 1;
+        if (B > 1e5 && B > 3 * r.index)
+          throw Error(
+            "potential infinite loop, way more iterations than matches",
+          );
+        return ((A += i), i.length);
+      }
+      var E = T(e);
+      if (!E)
+        throw (
+          console.error(g.replace("{}", e)),
+          Error('Unknown language: "' + e + '"')
+        );
+      var _ = (function (e) {
+          function n(n, t) {
+            return RegExp(
+              d(n),
+              "m" + (e.case_insensitive ? "i" : "") + (t ? "g" : ""),
+            );
+          }
+          class t {
+            constructor() {
+              ((this.matchIndexes = {}),
+                (this.regexes = []),
+                (this.matchAt = 1),
+                (this.position = 0));
+            }
+            addRule(e, n) {
+              ((n.position = this.position++),
+                (this.matchIndexes[this.matchAt] = n),
+                this.regexes.push([n, e]),
+                (this.matchAt +=
+                  (function (e) {
+                    return RegExp(e.toString() + "|").exec("").length - 1;
+                  })(e) + 1));
+            }
+            compile() {
+              0 === this.regexes.length && (this.exec = () => null);
+              const e = this.regexes.map((e) => e[1]);
+              ((this.matcherRe = n(
+                (function (e, n = "|") {
+                  for (
+                    var t = /\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./,
+                      r = 0,
+                      a = "",
+                      i = 0;
+                    i < e.length;
+                    i++
+                  ) {
+                    var s = (r += 1),
+                      o = d(e[i]);
+                    for (i > 0 && (a += n), a += "("; o.length > 0; ) {
+                      var l = t.exec(o);
+                      if (null == l) {
+                        a += o;
+                        break;
+                      }
+                      ((a += o.substring(0, l.index)),
+                        (o = o.substring(l.index + l[0].length)),
+                        "\\" === l[0][0] && l[1]
+                          ? (a += "\\" + (+l[1] + s))
+                          : ((a += l[0]), "(" === l[0] && r++));
+                    }
+                    a += ")";
+                  }
+                  return a;
+                })(e),
+                !0,
+              )),
+                (this.lastIndex = 0));
+            }
+            exec(e) {
+              this.matcherRe.lastIndex = this.lastIndex;
+              const n = this.matcherRe.exec(e);
+              if (!n) return null;
+              const t = n.findIndex((e, n) => n > 0 && void 0 !== e),
+                r = this.matchIndexes[t];
+              return (n.splice(0, t), Object.assign(n, r));
+            }
+          }
+          class a {
+            constructor() {
+              ((this.rules = []),
+                (this.multiRegexes = []),
+                (this.count = 0),
+                (this.lastIndex = 0),
+                (this.regexIndex = 0));
+            }
+            getMatcher(e) {
+              if (this.multiRegexes[e]) return this.multiRegexes[e];
+              const n = new t();
+              return (
+                this.rules.slice(e).forEach(([e, t]) => n.addRule(e, t)),
+                n.compile(),
+                (this.multiRegexes[e] = n),
+                n
+              );
+            }
+            considerAll() {
+              this.regexIndex = 0;
+            }
+            addRule(e, n) {
+              (this.rules.push([e, n]), "begin" === n.type && this.count++);
+            }
+            exec(e) {
+              const n = this.getMatcher(this.regexIndex);
+              n.lastIndex = this.lastIndex;
+              const t = n.exec(e);
+              return (
+                t &&
+                  ((this.regexIndex += t.position + 1),
+                  this.regexIndex === this.count && (this.regexIndex = 0)),
+                t
+              );
+            }
+          }
+          function i(e, n) {
+            const t = e.input[e.index - 1],
+              r = e.input[e.index + e[0].length];
+            ("." !== t && "." !== r) || n.ignoreMatch();
+          }
+          if (e.contains && e.contains.includes("self"))
+            throw Error(
+              "ERR: contains `self` is not supported at the top-level of a language.  See documentation.",
+            );
+          return (function t(s, o) {
+            const l = s;
+            if (s.compiled) return l;
+            ((s.compiled = !0),
+              (s.__beforeBegin = null),
+              (s.keywords = s.keywords || s.beginKeywords));
+            let c = null;
+            if (
+              ("object" == typeof s.keywords &&
+                ((c = s.keywords.$pattern), delete s.keywords.$pattern),
+              s.keywords &&
+                (s.keywords = (function (e, n) {
+                  var t = {};
+                  return (
+                    "string" == typeof e
+                      ? r("keyword", e)
+                      : Object.keys(e).forEach(function (n) {
+                          r(n, e[n]);
+                        }),
+                    t
+                  );
+                  function r(e, r) {
+                    (n && (r = r.toLowerCase()),
+                      r.split(" ").forEach(function (n) {
+                        var r = n.split("|");
+                        t[r[0]] = [e, w(r[0], r[1])];
+                      }));
+                  }
+                })(s.keywords, e.case_insensitive)),
+              s.lexemes && c)
+            )
+              throw Error(
+                "ERR: Prefer `keywords.$pattern` to `mode.lexemes`, BOTH are not allowed. (see mode reference) ",
+              );
+            return (
+              (l.keywordPatternRe = n(s.lexemes || c || /\w+/, !0)),
+              o &&
+                (s.beginKeywords &&
+                  ((s.begin =
+                    "\\b(" +
+                    s.beginKeywords.split(" ").join("|") +
+                    ")(?=\\b|\\s)"),
+                  (s.__beforeBegin = i)),
+                s.begin || (s.begin = /\B|\b/),
+                (l.beginRe = n(s.begin)),
+                s.endSameAsBegin && (s.end = s.begin),
+                s.end || s.endsWithParent || (s.end = /\B|\b/),
+                s.end && (l.endRe = n(s.end)),
+                (l.terminator_end = d(s.end) || ""),
+                s.endsWithParent &&
+                  o.terminator_end &&
+                  (l.terminator_end += (s.end ? "|" : "") + o.terminator_end)),
+              s.illegal && (l.illegalRe = n(s.illegal)),
+              void 0 === s.relevance && (s.relevance = 1),
+              s.contains || (s.contains = []),
+              (s.contains = [].concat(
+                ...s.contains.map(function (e) {
+                  return (function (e) {
+                    return (
+                      e.variants &&
+                        !e.cached_variants &&
+                        (e.cached_variants = e.variants.map(function (n) {
+                          return r(e, { variants: null }, n);
+                        })),
+                      e.cached_variants
+                        ? e.cached_variants
+                        : (function e(n) {
+                              return !!n && (n.endsWithParent || e(n.starts));
+                            })(e)
+                          ? r(e, { starts: e.starts ? r(e.starts) : null })
+                          : Object.isFrozen(e)
+                            ? r(e)
+                            : e
+                    );
+                  })("self" === e ? s : e);
+                }),
+              )),
+              s.contains.forEach(function (e) {
+                t(e, l);
+              }),
+              s.starts && t(s.starts, o),
+              (l.matcher = (function (e) {
+                const n = new a();
+                return (
+                  e.contains.forEach((e) =>
+                    n.addRule(e.begin, { rule: e, type: "begin" }),
+                  ),
+                  e.terminator_end &&
+                    n.addRule(e.terminator_end, { type: "end" }),
+                  e.illegal && n.addRule(e.illegal, { type: "illegal" }),
+                  n
+                );
+              })(l)),
+              l
+            );
+          })(e);
+        })(E),
+        N = "",
+        y = s || _,
+        O = {},
+        k = new f.__emitter(f);
+      !(function () {
+        for (var e = [], n = y; n !== E; n = n.parent)
+          n.className && e.unshift(n.className);
+        e.forEach((e) => k.openNode(e));
+      })();
+      var A = "",
+        I = 0,
+        S = 0,
+        B = 0,
+        L = !1;
+      try {
+        for (y.matcher.considerAll(); ; ) {
+          (B++,
+            L
+              ? (L = !1)
+              : ((y.matcher.lastIndex = S), y.matcher.considerAll()));
+          const e = y.matcher.exec(o);
+          if (!e) break;
+          const n = x(o.substring(S, e.index), e);
+          S = e.index + n;
+        }
+        return (
+          x(o.substr(S)),
+          k.closeAllNodes(),
+          k.finalize(),
+          (N = k.toHTML()),
+          {
+            relevance: I,
+            value: N,
+            language: e,
+            illegal: !1,
+            emitter: k,
+            top: y,
+          }
+        );
+      } catch (n) {
+        if (n.message && n.message.includes("Illegal"))
+          return {
+            illegal: !0,
+            illegalBy: {
+              msg: n.message,
+              context: o.slice(S - 100, S + 100),
+              mode: n.mode,
+            },
+            sofar: N,
+            relevance: 0,
+            value: R(o),
+            emitter: k,
+          };
+        if (l)
+          return {
+            illegal: !1,
+            relevance: 0,
+            value: R(o),
+            emitter: k,
+            language: e,
+            top: y,
+            errorRaised: n,
+          };
+        throw n;
+      }
+    }
+    function v(e, n) {
+      n = n || f.languages || Object.keys(i);
+      var t = (function (e) {
+          const n = {
+            relevance: 0,
+            emitter: new f.__emitter(f),
+            value: R(e),
+            illegal: !1,
+            top: h,
+          };
+          return (n.emitter.addText(e), n);
+        })(e),
+        r = t;
+      return (
+        n
+          .filter(T)
+          .filter(I)
+          .forEach(function (n) {
+            var a = m(n, e, !1);
+            ((a.language = n),
+              a.relevance > r.relevance && (r = a),
+              a.relevance > t.relevance && ((r = t), (t = a)));
+          }),
+        r.language && (t.second_best = r),
+        t
+      );
+    }
+    function x(e) {
+      return f.tabReplace || f.useBR
+        ? e.replace(c, (e) =>
+            "\n" === e
+              ? f.useBR
+                ? "<br>"
+                : e
+              : f.tabReplace
+                ? e.replace(/\t/g, f.tabReplace)
+                : e,
+          )
+        : e;
+    }
+    function E(e) {
+      let n = null;
+      const t = (function (e) {
+        var n = e.className + " ";
+        n += e.parentNode ? e.parentNode.className : "";
+        const t = f.languageDetectRe.exec(n);
+        if (t) {
+          var r = T(t[1]);
+          return (
+            r ||
+              (console.warn(g.replace("{}", t[1])),
+              console.warn(
+                "Falling back to no-highlight mode for this block.",
+                e,
+              )),
+            r ? t[1] : "no-highlight"
+          );
+        }
+        return n.split(/\s+/).find((e) => p(e) || T(e));
+      })(e);
+      if (p(t)) return;
+      (S("before:highlightBlock", { block: e, language: t }),
+        f.useBR
+          ? ((n = document.createElement("div")).innerHTML = e.innerHTML
+              .replace(/\n/g, "")
+              .replace(/<br[ /]*>/g, "\n"))
+          : (n = e));
+      const r = n.textContent,
+        a = t ? b(t, r, !0) : v(r),
+        i = O(n);
+      if (i.length) {
+        const e = document.createElement("div");
+        ((e.innerHTML = a.value), (a.value = k(i, O(e), r)));
+      }
+      ((a.value = x(a.value)),
+        S("after:highlightBlock", { block: e, result: a }),
+        (e.innerHTML = a.value),
+        (e.className = (function (e, n, t) {
+          var r = n ? s[n] : t,
+            a = [e.trim()];
+          return (
+            e.match(/\bhljs\b/) || a.push("hljs"),
+            e.includes(r) || a.push(r),
+            a.join(" ").trim()
+          );
+        })(e.className, t, a.language)),
+        (e.result = {
+          language: a.language,
+          re: a.relevance,
+          relavance: a.relevance,
+        }),
+        a.second_best &&
+          (e.second_best = {
+            language: a.second_best.language,
+            re: a.second_best.relevance,
+            relavance: a.second_best.relevance,
+          }));
+    }
+    const N = () => {
+      if (!N.called) {
+        N.called = !0;
+        var e = document.querySelectorAll("pre code");
+        a.forEach.call(e, E);
+      }
+    };
+    function T(e) {
+      return ((e = (e || "").toLowerCase()), i[e] || i[s[e]]);
+    }
+    function A(e, { languageName: n }) {
+      ("string" == typeof e && (e = [e]),
+        e.forEach((e) => {
+          s[e] = n;
+        }));
+    }
+    function I(e) {
+      var n = T(e);
+      return n && !n.disableAutodetect;
+    }
+    function S(e, n) {
+      var t = e;
+      o.forEach(function (e) {
+        e[t] && e[t](n);
+      });
+    }
+    (Object.assign(t, {
+      highlight: b,
+      highlightAuto: v,
+      fixMarkup: x,
+      highlightBlock: E,
+      configure: function (e) {
+        f = y(f, e);
+      },
+      initHighlighting: N,
+      initHighlightingOnLoad: function () {
+        window.addEventListener("DOMContentLoaded", N, !1);
+      },
+      registerLanguage: function (e, n) {
+        var r = null;
+        try {
+          r = n(t);
+        } catch (n) {
+          if (
+            (console.error(
+              "Language definition for '{}' could not be registered.".replace(
+                "{}",
+                e,
+              ),
+            ),
+            !l)
+          )
+            throw n;
+          (console.error(n), (r = h));
+        }
+        (r.name || (r.name = e),
+          (i[e] = r),
+          (r.rawDefinition = n.bind(null, t)),
+          r.aliases && A(r.aliases, { languageName: e }));
+      },
+      listLanguages: function () {
+        return Object.keys(i);
+      },
+      getLanguage: T,
+      registerAliases: A,
+      requireLanguage: function (e) {
+        var n = T(e);
+        if (n) return n;
+        throw Error(
+          "The '{}' language is required, but not loaded.".replace("{}", e),
+        );
+      },
+      autoDetection: I,
+      inherit: y,
+      addPlugin: function (e) {
+        o.push(e);
+      },
+    }),
+      (t.debugMode = function () {
+        l = !1;
+      }),
+      (t.safeMode = function () {
+        l = !0;
+      }),
+      (t.versionString = "10.1.2"));
+    for (const n in _) "object" == typeof _[n] && e(_[n]);
+    return (Object.assign(t, _), t);
+  })({});
+})();
+"object" == typeof exports &&
+  "undefined" != typeof module &&
+  (module.exports = hljs);
+hljs.registerLanguage(
+  "xml",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n = {
+          className: "symbol",
+          begin: "&[a-z]+;|&#[0-9]+;|&#x[a-f0-9]+;",
+        },
+        a = {
+          begin: "\\s",
+          contains: [
+            {
+              className: "meta-keyword",
+              begin: "#?[a-z_][a-z1-9_-]+",
+              illegal: "\\n",
+            },
+          ],
+        },
+        s = e.inherit(a, { begin: "\\(", end: "\\)" }),
+        t = e.inherit(e.APOS_STRING_MODE, { className: "meta-string" }),
+        i = e.inherit(e.QUOTE_STRING_MODE, { className: "meta-string" }),
+        c = {
+          endsWithParent: !0,
+          illegal: /</,
+          relevance: 0,
+          contains: [
+            { className: "attr", begin: "[A-Za-z0-9\\._:-]+", relevance: 0 },
+            {
+              begin: /=\s*/,
+              relevance: 0,
+              contains: [
+                {
+                  className: "string",
+                  endsParent: !0,
+                  variants: [
+                    { begin: /"/, end: /"/, contains: [n] },
+                    { begin: /'/, end: /'/, contains: [n] },
+                    { begin: /[^\s"'=<>`]+/ },
+                  ],
+                },
+              ],
+            },
+          ],
+        };
+      return {
+        name: "HTML, XML",
+        aliases: [
+          "html",
+          "xhtml",
+          "rss",
+          "atom",
+          "xjb",
+          "xsd",
+          "xsl",
+          "plist",
+          "wsf",
+          "svg",
+        ],
+        case_insensitive: !0,
+        contains: [
+          {
+            className: "meta",
+            begin: "<![a-z]",
+            end: ">",
+            relevance: 10,
+            contains: [
+              a,
+              i,
+              t,
+              s,
+              {
+                begin: "\\[",
+                end: "\\]",
+                contains: [
+                  {
+                    className: "meta",
+                    begin: "<![a-z]",
+                    end: ">",
+                    contains: [a, s, i, t],
+                  },
+                ],
+              },
+            ],
+          },
+          e.COMMENT("\x3c!--", "--\x3e", { relevance: 10 }),
+          { begin: "<\\!\\[CDATA\\[", end: "\\]\\]>", relevance: 10 },
+          n,
+          { className: "meta", begin: /<\?xml/, end: /\?>/, relevance: 10 },
+          {
+            className: "tag",
+            begin: "<style(?=\\s|>)",
+            end: ">",
+            keywords: { name: "style" },
+            contains: [c],
+            starts: {
+              end: "</style>",
+              returnEnd: !0,
+              subLanguage: ["css", "xml"],
+            },
+          },
+          {
+            className: "tag",
+            begin: "<script(?=\\s|>)",
+            end: ">",
+            keywords: { name: "script" },
+            contains: [c],
+            starts: {
+              end: "<\/script>",
+              returnEnd: !0,
+              subLanguage: ["javascript", "handlebars", "xml"],
+            },
+          },
+          {
+            className: "tag",
+            begin: "</?",
+            end: "/?>",
+            contains: [
+              { className: "name", begin: /[^\/><\s]+/, relevance: 0 },
+              c,
+            ],
+          },
+        ],
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "markdown",
+  (function () {
+    "use strict";
+    return function (n) {
+      const e = { begin: "<", end: ">", subLanguage: "xml", relevance: 0 },
+        a = {
+          begin: "\\[.+?\\][\\(\\[].*?[\\)\\]]",
+          returnBegin: !0,
+          contains: [
+            {
+              className: "string",
+              begin: "\\[",
+              end: "\\]",
+              excludeBegin: !0,
+              returnEnd: !0,
+              relevance: 0,
+            },
+            {
+              className: "link",
+              begin: "\\]\\(",
+              end: "\\)",
+              excludeBegin: !0,
+              excludeEnd: !0,
+            },
+            {
+              className: "symbol",
+              begin: "\\]\\[",
+              end: "\\]",
+              excludeBegin: !0,
+              excludeEnd: !0,
+            },
+          ],
+          relevance: 10,
+        },
+        i = {
+          className: "strong",
+          contains: [],
+          variants: [
+            { begin: /_{2}/, end: /_{2}/ },
+            { begin: /\*{2}/, end: /\*{2}/ },
+          ],
+        },
+        s = {
+          className: "emphasis",
+          contains: [],
+          variants: [
+            { begin: /\*(?!\*)/, end: /\*/ },
+            { begin: /_(?!_)/, end: /_/, relevance: 0 },
+          ],
+        };
+      (i.contains.push(s), s.contains.push(i));
+      var c = [e, a];
+      return (
+        (i.contains = i.contains.concat(c)),
+        (s.contains = s.contains.concat(c)),
+        {
+          name: "Markdown",
+          aliases: ["md", "mkdown", "mkd"],
+          contains: [
+            {
+              className: "section",
+              variants: [
+                { begin: "^#{1,6}", end: "$", contains: (c = c.concat(i, s)) },
+                {
+                  begin: "(?=^.+?\\n[=-]{2,}$)",
+                  contains: [
+                    { begin: "^[=-]*$" },
+                    { begin: "^", end: "\\n", contains: c },
+                  ],
+                },
+              ],
+            },
+            e,
+            {
+              className: "bullet",
+              begin: "^[ \t]*([*+-]|(\\d+\\.))(?=\\s+)",
+              end: "\\s+",
+              excludeEnd: !0,
+            },
+            i,
+            s,
+            { className: "quote", begin: "^>\\s+", contains: c, end: "$" },
+            {
+              className: "code",
+              variants: [
+                { begin: "(`{3,})(.|\\n)*?\\1`*[ ]*" },
+                { begin: "(~{3,})(.|\\n)*?\\1~*[ ]*" },
+                { begin: "```", end: "```+[ ]*$" },
+                { begin: "~~~", end: "~~~+[ ]*$" },
+                { begin: "`.+?`" },
+                {
+                  begin: "(?=^( {4}|\\t))",
+                  contains: [{ begin: "^( {4}|\\t)", end: "(\\n)$" }],
+                  relevance: 0,
+                },
+              ],
+            },
+            { begin: "^[-\\*]{3,}", end: "$" },
+            a,
+            {
+              begin: /^\[[^\n]+\]:/,
+              returnBegin: !0,
+              contains: [
+                {
+                  className: "symbol",
+                  begin: /\[/,
+                  end: /\]/,
+                  excludeBegin: !0,
+                  excludeEnd: !0,
+                },
+                {
+                  className: "link",
+                  begin: /:\s*/,
+                  end: /$/,
+                  excludeBegin: !0,
+                },
+              ],
+            },
+          ],
+        }
+      );
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "perl",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n = {
+          $pattern: /[\w.]+/,
+          keyword:
+            "getpwent getservent quotemeta msgrcv scalar kill dbmclose undef lc ma syswrite tr send umask sysopen shmwrite vec qx utime local oct semctl localtime readpipe do return format read sprintf dbmopen pop getpgrp not getpwnam rewinddir qq fileno qw endprotoent wait sethostent bless s|0 opendir continue each sleep endgrent shutdown dump chomp connect getsockname die socketpair close flock exists index shmget sub for endpwent redo lstat msgctl setpgrp abs exit select print ref gethostbyaddr unshift fcntl syscall goto getnetbyaddr join gmtime symlink semget splice x|0 getpeername recv log setsockopt cos last reverse gethostbyname getgrnam study formline endhostent times chop length gethostent getnetent pack getprotoent getservbyname rand mkdir pos chmod y|0 substr endnetent printf next open msgsnd readdir use unlink getsockopt getpriority rindex wantarray hex system getservbyport endservent int chr untie rmdir prototype tell listen fork shmread ucfirst setprotoent else sysseek link getgrgid shmctl waitpid unpack getnetbyname reset chdir grep split require caller lcfirst until warn while values shift telldir getpwuid my getprotobynumber delete and sort uc defined srand accept package seekdir getprotobyname semop our rename seek if q|0 chroot sysread setpwent no crypt getc chown sqrt write setnetent setpriority foreach tie sin msgget map stat getlogin unless elsif truncate exec keys glob tied closedir ioctl socket readlink eval xor readline binmode setservent eof ord bind alarm pipe atan2 getgrent exp time push setgrent gt lt or ne m|0 break given say state when",
+        },
+        t = { className: "subst", begin: "[$@]\\{", end: "\\}", keywords: n },
+        s = { begin: "->{", end: "}" },
+        r = {
+          variants: [
+            { begin: /\$\d/ },
+            { begin: /[\$%@](\^\w\b|#\w+(::\w+)*|{\w+}|\w+(::\w*)*)/ },
+            { begin: /[\$%@][^\s\w{]/, relevance: 0 },
+          ],
+        },
+        i = [e.BACKSLASH_ESCAPE, t, r],
+        a = [
+          r,
+          e.HASH_COMMENT_MODE,
+          e.COMMENT("^\\=\\w", "\\=cut", { endsWithParent: !0 }),
+          s,
+          {
+            className: "string",
+            contains: i,
+            variants: [
+              { begin: "q[qwxr]?\\s*\\(", end: "\\)", relevance: 5 },
+              { begin: "q[qwxr]?\\s*\\[", end: "\\]", relevance: 5 },
+              { begin: "q[qwxr]?\\s*\\{", end: "\\}", relevance: 5 },
+              { begin: "q[qwxr]?\\s*\\|", end: "\\|", relevance: 5 },
+              { begin: "q[qwxr]?\\s*\\<", end: "\\>", relevance: 5 },
+              { begin: "qw\\s+q", end: "q", relevance: 5 },
+              { begin: "'", end: "'", contains: [e.BACKSLASH_ESCAPE] },
+              { begin: '"', end: '"' },
+              { begin: "`", end: "`", contains: [e.BACKSLASH_ESCAPE] },
+              { begin: "{\\w+}", contains: [], relevance: 0 },
+              { begin: "-?\\w+\\s*\\=\\>", contains: [], relevance: 0 },
+            ],
+          },
+          {
+            className: "number",
+            begin:
+              "(\\b0[0-7_]+)|(\\b0x[0-9a-fA-F_]+)|(\\b[1-9][0-9_]*(\\.[0-9_]+)?)|[0_]\\b",
+            relevance: 0,
+          },
+          {
+            begin:
+              "(\\/\\/|" +
+              e.RE_STARTERS_RE +
+              "|\\b(split|return|print|reverse|grep)\\b)\\s*",
+            keywords: "split return print reverse grep",
+            relevance: 0,
+            contains: [
+              e.HASH_COMMENT_MODE,
+              {
+                className: "regexp",
+                begin: "(s|tr|y)/(\\\\.|[^/])*/(\\\\.|[^/])*/[a-z]*",
+                relevance: 10,
+              },
+              {
+                className: "regexp",
+                begin: "(m|qr)?/",
+                end: "/[a-z]*",
+                contains: [e.BACKSLASH_ESCAPE],
+                relevance: 0,
+              },
+            ],
+          },
+          {
+            className: "function",
+            beginKeywords: "sub",
+            end: "(\\s*\\(.*?\\))?[;{]",
+            excludeEnd: !0,
+            relevance: 5,
+            contains: [e.TITLE_MODE],
+          },
+          { begin: "-\\w\\b", relevance: 0 },
+          {
+            begin: "^__DATA__$",
+            end: "^__END__$",
+            subLanguage: "mojolicious",
+            contains: [{ begin: "^@@.*", end: "$", className: "comment" }],
+          },
+        ];
+      return (
+        (t.contains = a),
+        (s.contains = a),
+        { name: "Perl", aliases: ["pl", "pm"], keywords: n, contains: a }
+      );
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "plaintext",
+  (function () {
+    "use strict";
+    return function (t) {
+      return {
+        name: "Plain text",
+        aliases: ["text", "txt"],
+        disableAutodetect: !0,
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "ini",
+  (function () {
+    "use strict";
+    function e(e) {
+      return e ? ("string" == typeof e ? e : e.source) : null;
+    }
+    function n(...n) {
+      return n.map((n) => e(n)).join("");
+    }
+    return function (a) {
+      var s = {
+          className: "number",
+          relevance: 0,
+          variants: [
+            { begin: /([\+\-]+)?[\d]+_[\d_]+/ },
+            { begin: a.NUMBER_RE },
+          ],
+        },
+        i = a.COMMENT();
+      i.variants = [
+        { begin: /;/, end: /$/ },
+        { begin: /#/, end: /$/ },
+      ];
+      var t = {
+          className: "variable",
+          variants: [{ begin: /\$[\w\d"][\w\d_]*/ }, { begin: /\$\{(.*?)}/ }],
+        },
+        r = { className: "literal", begin: /\bon|off|true|false|yes|no\b/ },
+        l = {
+          className: "string",
+          contains: [a.BACKSLASH_ESCAPE],
+          variants: [
+            { begin: "'''", end: "'''", relevance: 10 },
+            { begin: '"""', end: '"""', relevance: 10 },
+            { begin: '"', end: '"' },
+            { begin: "'", end: "'" },
+          ],
+        },
+        c = {
+          begin: /\[/,
+          end: /\]/,
+          contains: [i, r, t, l, s, "self"],
+          relevance: 0,
+        },
+        g =
+          "(" +
+          [/[A-Za-z0-9_-]+/, /"(\\"|[^"])*"/, /'[^']*'/]
+            .map((n) => e(n))
+            .join("|") +
+          ")";
+      return {
+        name: "TOML, also INI",
+        aliases: ["toml"],
+        case_insensitive: !0,
+        illegal: /\S/,
+        contains: [
+          i,
+          { className: "section", begin: /\[+/, end: /\]+/ },
+          {
+            begin: n(
+              g,
+              "(\\s*\\.\\s*",
+              g,
+              ")*",
+              n("(?=", /\s*=\s*[^#\s]/, ")"),
+            ),
+            className: "attr",
+            starts: { end: /$/, contains: [i, c, r, t, l, s] },
+          },
+        ],
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "json",
+  (function () {
+    "use strict";
+    return function (n) {
+      var e = { literal: "true false null" },
+        i = [n.C_LINE_COMMENT_MODE, n.C_BLOCK_COMMENT_MODE],
+        t = [n.QUOTE_STRING_MODE, n.C_NUMBER_MODE],
+        a = {
+          end: ",",
+          endsWithParent: !0,
+          excludeEnd: !0,
+          contains: t,
+          keywords: e,
+        },
+        l = {
+          begin: "{",
+          end: "}",
+          contains: [
+            {
+              className: "attr",
+              begin: /"/,
+              end: /"/,
+              contains: [n.BACKSLASH_ESCAPE],
+              illegal: "\\n",
+            },
+            n.inherit(a, { begin: /:/ }),
+          ].concat(i),
+          illegal: "\\S",
+        },
+        s = {
+          begin: "\\[",
+          end: "\\]",
+          contains: [n.inherit(a)],
+          illegal: "\\S",
+        };
+      return (
+        t.push(l, s),
+        i.forEach(function (n) {
+          t.push(n);
+        }),
+        { name: "JSON", contains: t, keywords: e, illegal: "\\S" }
+      );
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "ruby",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n =
+          "[a-zA-Z_]\\w*[!?=]?|[-+~]\\@|<<|>>|=~|===?|<=>|[<>]=?|\\*\\*|[-/+%^&*~`|]|\\[\\]=?",
+        a = {
+          keyword:
+            "and then defined module in return redo if BEGIN retry end for self when next until do begin unless END rescue else break undef not super class case require yield alias while ensure elsif or include attr_reader attr_writer attr_accessor",
+          literal: "true false nil",
+        },
+        s = { className: "doctag", begin: "@[A-Za-z]+" },
+        i = { begin: "#<", end: ">" },
+        r = [
+          e.COMMENT("#", "$", { contains: [s] }),
+          e.COMMENT("^\\=begin", "^\\=end", { contains: [s], relevance: 10 }),
+          e.COMMENT("^__END__", "\\n$"),
+        ],
+        c = { className: "subst", begin: "#\\{", end: "}", keywords: a },
+        t = {
+          className: "string",
+          contains: [e.BACKSLASH_ESCAPE, c],
+          variants: [
+            { begin: /'/, end: /'/ },
+            { begin: /"/, end: /"/ },
+            { begin: /`/, end: /`/ },
+            { begin: "%[qQwWx]?\\(", end: "\\)" },
+            { begin: "%[qQwWx]?\\[", end: "\\]" },
+            { begin: "%[qQwWx]?{", end: "}" },
+            { begin: "%[qQwWx]?<", end: ">" },
+            { begin: "%[qQwWx]?/", end: "/" },
+            { begin: "%[qQwWx]?%", end: "%" },
+            { begin: "%[qQwWx]?-", end: "-" },
+            { begin: "%[qQwWx]?\\|", end: "\\|" },
+            {
+              begin:
+                /\B\?(\\\d{1,3}|\\x[A-Fa-f0-9]{1,2}|\\u[A-Fa-f0-9]{4}|\\?\S)\b/,
+            },
+            {
+              begin: /<<[-~]?'?(\w+)(?:.|\n)*?\n\s*\1\b/,
+              returnBegin: !0,
+              contains: [
+                { begin: /<<[-~]?'?/ },
+                e.END_SAME_AS_BEGIN({
+                  begin: /(\w+)/,
+                  end: /(\w+)/,
+                  contains: [e.BACKSLASH_ESCAPE, c],
+                }),
+              ],
+            },
+          ],
+        },
+        b = {
+          className: "params",
+          begin: "\\(",
+          end: "\\)",
+          endsParent: !0,
+          keywords: a,
+        },
+        d = [
+          t,
+          i,
+          {
+            className: "class",
+            beginKeywords: "class module",
+            end: "$|;",
+            illegal: /=/,
+            contains: [
+              e.inherit(e.TITLE_MODE, {
+                begin: "[A-Za-z_]\\w*(::\\w+)*(\\?|\\!)?",
+              }),
+              {
+                begin: "<\\s*",
+                contains: [{ begin: "(" + e.IDENT_RE + "::)?" + e.IDENT_RE }],
+              },
+            ].concat(r),
+          },
+          {
+            className: "function",
+            beginKeywords: "def",
+            end: "$|;",
+            contains: [e.inherit(e.TITLE_MODE, { begin: n }), b].concat(r),
+          },
+          { begin: e.IDENT_RE + "::" },
+          {
+            className: "symbol",
+            begin: e.UNDERSCORE_IDENT_RE + "(\\!|\\?)?:",
+            relevance: 0,
+          },
+          {
+            className: "symbol",
+            begin: ":(?!\\s)",
+            contains: [t, { begin: n }],
+            relevance: 0,
+          },
+          {
+            className: "number",
+            begin:
+              "(\\b0[0-7_]+)|(\\b0x[0-9a-fA-F_]+)|(\\b[1-9][0-9_]*(\\.[0-9_]+)?)|[0_]\\b",
+            relevance: 0,
+          },
+          { begin: "(\\$\\W)|((\\$|\\@\\@?)(\\w+))" },
+          { className: "params", begin: /\|/, end: /\|/, keywords: a },
+          {
+            begin: "(" + e.RE_STARTERS_RE + "|unless)\\s*",
+            keywords: "unless",
+            contains: [
+              i,
+              {
+                className: "regexp",
+                contains: [e.BACKSLASH_ESCAPE, c],
+                illegal: /\n/,
+                variants: [
+                  { begin: "/", end: "/[a-z]*" },
+                  { begin: "%r{", end: "}[a-z]*" },
+                  { begin: "%r\\(", end: "\\)[a-z]*" },
+                  { begin: "%r!", end: "![a-z]*" },
+                  { begin: "%r\\[", end: "\\][a-z]*" },
+                ],
+              },
+            ].concat(r),
+            relevance: 0,
+          },
+        ].concat(r);
+      ((c.contains = d), (b.contains = d));
+      var g = [
+        { begin: /^\s*=>/, starts: { end: "$", contains: d } },
+        {
+          className: "meta",
+          begin:
+            "^([>?]>|[\\w#]+\\(\\w+\\):\\d+:\\d+>|(\\w+-)?\\d+\\.\\d+\\.\\d(p\\d+)?[^>]+>)",
+          starts: { end: "$", contains: d },
+        },
+      ];
+      return {
+        name: "Ruby",
+        aliases: ["rb", "gemspec", "podspec", "thor", "irb"],
+        keywords: a,
+        illegal: /\/\*/,
+        contains: r.concat(g).concat(d),
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "yaml",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n = "true false yes no null",
+        a = "[\\w#;/?:@&=+$,.~*\\'()[\\]]+",
+        s = {
+          className: "string",
+          relevance: 0,
+          variants: [
+            { begin: /'/, end: /'/ },
+            { begin: /"/, end: /"/ },
+            { begin: /\S+/ },
+          ],
+          contains: [
+            e.BACKSLASH_ESCAPE,
+            {
+              className: "template-variable",
+              variants: [
+                { begin: "{{", end: "}}" },
+                { begin: "%{", end: "}" },
+              ],
+            },
+          ],
+        },
+        i = e.inherit(s, {
+          variants: [
+            { begin: /'/, end: /'/ },
+            { begin: /"/, end: /"/ },
+            { begin: /[^\s,{}[\]]+/ },
+          ],
+        }),
+        l = {
+          end: ",",
+          endsWithParent: !0,
+          excludeEnd: !0,
+          contains: [],
+          keywords: n,
+          relevance: 0,
+        },
+        t = {
+          begin: "{",
+          end: "}",
+          contains: [l],
+          illegal: "\\n",
+          relevance: 0,
+        },
+        g = {
+          begin: "\\[",
+          end: "\\]",
+          contains: [l],
+          illegal: "\\n",
+          relevance: 0,
+        },
+        b = [
+          {
+            className: "attr",
+            variants: [
+              { begin: "\\w[\\w :\\/.-]*:(?=[ \t]|$)" },
+              { begin: '"\\w[\\w :\\/.-]*":(?=[ \t]|$)' },
+              { begin: "'\\w[\\w :\\/.-]*':(?=[ \t]|$)" },
+            ],
+          },
+          { className: "meta", begin: "^---s*$", relevance: 10 },
+          {
+            className: "string",
+            begin: "[\\|>]([0-9]?[+-])?[ ]*\\n( *)[\\S ]+\\n(\\2[\\S ]+\\n?)*",
+          },
+          {
+            begin: "<%[%=-]?",
+            end: "[%-]?%>",
+            subLanguage: "ruby",
+            excludeBegin: !0,
+            excludeEnd: !0,
+            relevance: 0,
+          },
+          { className: "type", begin: "!\\w+!" + a },
+          { className: "type", begin: "!<" + a + ">" },
+          { className: "type", begin: "!" + a },
+          { className: "type", begin: "!!" + a },
+          { className: "meta", begin: "&" + e.UNDERSCORE_IDENT_RE + "$" },
+          { className: "meta", begin: "\\*" + e.UNDERSCORE_IDENT_RE + "$" },
+          { className: "bullet", begin: "\\-(?=[ ]|$)", relevance: 0 },
+          e.HASH_COMMENT_MODE,
+          { beginKeywords: n, keywords: { literal: n } },
+          {
+            className: "number",
+            begin:
+              "\\b[0-9]{4}(-[0-9][0-9]){0,2}([Tt \\t][0-9][0-9]?(:[0-9][0-9]){2})?(\\.[0-9]*)?([ \\t])*(Z|[-+][0-9][0-9]?(:[0-9][0-9])?)?\\b",
+          },
+          { className: "number", begin: e.C_NUMBER_RE + "\\b" },
+          t,
+          g,
+          s,
+        ],
+        c = [...b];
+      return (
+        c.pop(),
+        c.push(i),
+        (l.contains = c),
+        {
+          name: "YAML",
+          case_insensitive: !0,
+          aliases: ["yml", "YAML"],
+          contains: b,
+        }
+      );
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "haskell",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n = {
+          variants: [
+            e.COMMENT("--", "$"),
+            e.COMMENT("{-", "-}", { contains: ["self"] }),
+          ],
+        },
+        i = { className: "meta", begin: "{-#", end: "#-}" },
+        a = { className: "meta", begin: "^#", end: "$" },
+        s = { className: "type", begin: "\\b[A-Z][\\w']*", relevance: 0 },
+        l = {
+          begin: "\\(",
+          end: "\\)",
+          illegal: '"',
+          contains: [
+            i,
+            a,
+            {
+              className: "type",
+              begin: "\\b[A-Z][\\w]*(\\((\\.\\.|,|\\w+)\\))?",
+            },
+            e.inherit(e.TITLE_MODE, { begin: "[_a-z][\\w']*" }),
+            n,
+          ],
+        };
+      return {
+        name: "Haskell",
+        aliases: ["hs"],
+        keywords:
+          "let in if then else case of where do module import hiding qualified type data newtype deriving class instance as default infix infixl infixr foreign export ccall stdcall cplusplus jvm dotnet safe unsafe family forall mdo proc rec",
+        contains: [
+          {
+            beginKeywords: "module",
+            end: "where",
+            keywords: "module where",
+            contains: [l, n],
+            illegal: "\\W\\.|;",
+          },
+          {
+            begin: "\\bimport\\b",
+            end: "$",
+            keywords: "import qualified as hiding",
+            contains: [l, n],
+            illegal: "\\W\\.|;",
+          },
+          {
+            className: "class",
+            begin: "^(\\s*)?(class|instance)\\b",
+            end: "where",
+            keywords: "class family instance where",
+            contains: [s, l, n],
+          },
+          {
+            className: "class",
+            begin: "\\b(data|(new)?type)\\b",
+            end: "$",
+            keywords: "data family type newtype deriving",
+            contains: [
+              i,
+              s,
+              l,
+              { begin: "{", end: "}", contains: l.contains },
+              n,
+            ],
+          },
+          { beginKeywords: "default", end: "$", contains: [s, l, n] },
+          {
+            beginKeywords: "infix infixl infixr",
+            end: "$",
+            contains: [e.C_NUMBER_MODE, n],
+          },
+          {
+            begin: "\\bforeign\\b",
+            end: "$",
+            keywords:
+              "foreign import export ccall stdcall cplusplus jvm dotnet safe unsafe",
+            contains: [s, e.QUOTE_STRING_MODE, n],
+          },
+          {
+            className: "meta",
+            begin: "#!\\/usr\\/bin\\/env runhaskell",
+            end: "$",
+          },
+          i,
+          a,
+          e.QUOTE_STRING_MODE,
+          e.C_NUMBER_MODE,
+          s,
+          e.inherit(e.TITLE_MODE, { begin: "^[_a-z][\\w']*" }),
+          n,
+          { begin: "->|<-" },
+        ],
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "nix",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n = {
+          keyword: "rec with let in inherit assert if else then",
+          literal: "true false or and null",
+          built_in:
+            "import abort baseNameOf dirOf isNull builtins map removeAttrs throw toString derivation",
+        },
+        i = { className: "subst", begin: /\$\{/, end: /}/, keywords: n },
+        t = {
+          className: "string",
+          contains: [i],
+          variants: [
+            { begin: "''", end: "''" },
+            { begin: '"', end: '"' },
+          ],
+        },
+        s = [
+          e.NUMBER_MODE,
+          e.HASH_COMMENT_MODE,
+          e.C_BLOCK_COMMENT_MODE,
+          t,
+          {
+            begin: /[a-zA-Z0-9-_]+(\s*=)/,
+            returnBegin: !0,
+            relevance: 0,
+            contains: [{ className: "attr", begin: /\S+/ }],
+          },
+        ];
+      return (
+        (i.contains = s),
+        { name: "Nix", aliases: ["nixos"], keywords: n, contains: s }
+      );
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "bash",
+  (function () {
+    "use strict";
+    return function (e) {
+      const s = {};
+      Object.assign(s, {
+        className: "variable",
+        variants: [
+          { begin: /\$[\w\d#@][\w\d_]*/ },
+          {
+            begin: /\$\{/,
+            end: /\}/,
+            contains: [{ begin: /:-/, contains: [s] }],
+          },
+        ],
+      });
+      const t = {
+          className: "subst",
+          begin: /\$\(/,
+          end: /\)/,
+          contains: [e.BACKSLASH_ESCAPE],
+        },
+        n = {
+          className: "string",
+          begin: /"/,
+          end: /"/,
+          contains: [e.BACKSLASH_ESCAPE, s, t],
+        };
+      t.contains.push(n);
+      const a = {
+          begin: /\$\(\(/,
+          end: /\)\)/,
+          contains: [
+            { begin: /\d+#[0-9a-f]+/, className: "number" },
+            e.NUMBER_MODE,
+            s,
+          ],
+        },
+        i = e.SHEBANG({
+          binary: "(fish|bash|zsh|sh|csh|ksh|tcsh|dash|scsh)",
+          relevance: 10,
+        }),
+        c = {
+          className: "function",
+          begin: /\w[\w\d_]*\s*\(\s*\)\s*\{/,
+          returnBegin: !0,
+          contains: [e.inherit(e.TITLE_MODE, { begin: /\w[\w\d_]*/ })],
+          relevance: 0,
+        };
+      return {
+        name: "Bash",
+        aliases: ["sh", "zsh"],
+        keywords: {
+          $pattern: /\b-?[a-z\._]+\b/,
+          keyword:
+            "if then else elif fi for while in do done case esac function",
+          literal: "true false",
+          built_in:
+            "break cd continue eval exec exit export getopts hash pwd readonly return shift test times trap umask unset alias bind builtin caller command declare echo enable help let local logout mapfile printf read readarray source type typeset ulimit unalias set shopt autoload bg bindkey bye cap chdir clone comparguments compcall compctl compdescribe compfiles compgroups compquote comptags comptry compvalues dirs disable disown echotc echoti emulate fc fg float functions getcap getln history integer jobs kill limit log noglob popd print pushd pushln rehash sched setcap setopt stat suspend ttyctl unfunction unhash unlimit unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof zpty zregexparse zsocket zstyle ztcp",
+          _: "-ne -eq -lt -gt -f -d -e -s -l -a",
+        },
+        contains: [
+          i,
+          e.SHEBANG(),
+          c,
+          a,
+          e.HASH_COMMENT_MODE,
+          n,
+          { className: "", begin: /\\"/ },
+          { className: "string", begin: /'/, end: /'/ },
+          s,
+        ],
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "shell",
+  (function () {
+    "use strict";
+    return function (s) {
+      return {
+        name: "Shell Session",
+        aliases: ["console"],
+        contains: [
+          {
+            className: "meta",
+            begin: "^\\s{0,3}[/\\w\\d\\[\\]()@-]*[>%$#]",
+            starts: { end: "$", subLanguage: "bash" },
+          },
+        ],
+      };
+    };
+  })(),
+);
+hljs.registerLanguage(
+  "python",
+  (function () {
+    "use strict";
+    return function (e) {
+      var n = {
+          keyword:
+            "and elif is global as in if from raise for except finally print import pass return exec else break not with class assert yield try while continue del or def lambda async await nonlocal|10",
+          built_in: "Ellipsis NotImplemented",
+          literal: "False None True",
+        },
+        a = { className: "meta", begin: /^(>>>|\.\.\.) / },
+        i = {
+          className: "subst",
+          begin: /\{/,
+          end: /\}/,
+          keywords: n,
+          illegal: /#/,
+        },
+        s = { begin: /\{\{/, relevance: 0 },
+        r = {
+          className: "string",
+          contains: [e.BACKSLASH_ESCAPE],
+          variants: [
+            {
+              begin: /(u|b)?r?'''/,
+              end: /'''/,
+              contains: [e.BACKSLASH_ESCAPE, a],
+              relevance: 10,
+            },
+            {
+              begin: /(u|b)?r?"""/,
+              end: /"""/,
+              contains: [e.BACKSLASH_ESCAPE, a],
+              relevance: 10,
+            },
+            {
+              begin: /(fr|rf|f)'''/,
+              end: /'''/,
+              contains: [e.BACKSLASH_ESCAPE, a, s, i],
+            },
+            {
+              begin: /(fr|rf|f)"""/,
+              end: /"""/,
+              contains: [e.BACKSLASH_ESCAPE, a, s, i],
+            },
+            { begin: /(u|r|ur)'/, end: /'/, relevance: 10 },
+            { begin: /(u|r|ur)"/, end: /"/, relevance: 10 },
+            { begin: /(b|br)'/, end: /'/ },
+            { begin: /(b|br)"/, end: /"/ },
+            {
+              begin: /(fr|rf|f)'/,
+              end: /'/,
+              contains: [e.BACKSLASH_ESCAPE, s, i],
+            },
+            {
+              begin: /(fr|rf|f)"/,
+              end: /"/,
+              contains: [e.BACKSLASH_ESCAPE, s, i],
+            },
+            e.APOS_STRING_MODE,
+            e.QUOTE_STRING_MODE,
+          ],
+        },
+        l = {
+          className: "number",
+          relevance: 0,
+          variants: [
+            { begin: e.BINARY_NUMBER_RE + "[lLjJ]?" },
+            { begin: "\\b(0o[0-7]+)[lLjJ]?" },
+            { begin: e.C_NUMBER_RE + "[lLjJ]?" },
+          ],
+        },
+        t = {
+          className: "params",
+          variants: [
+            { begin: /\(\s*\)/, skip: !0, className: null },
+            {
+              begin: /\(/,
+              end: /\)/,
+              excludeBegin: !0,
+              excludeEnd: !0,
+              contains: ["self", a, l, r, e.HASH_COMMENT_MODE],
+            },
+          ],
+        };
+      return (
+        (i.contains = [r, l, a]),
+        {
+          name: "Python",
+          aliases: ["py", "gyp", "ipython"],
+          keywords: n,
+          illegal: /(<\/|->|\?)|=>/,
+          contains: [
+            a,
+            l,
+            { beginKeywords: "if", relevance: 0 },
+            r,
+            e.HASH_COMMENT_MODE,
+            {
+              variants: [
+                { className: "function", beginKeywords: "def" },
+                { className: "class", beginKeywords: "class" },
+              ],
+              end: /:/,
+              illegal: /[${=;\n,]/,
+              contains: [
+                e.UNDERSCORE_TITLE_MODE,
+                t,
+                { begin: /->/, endsWithParent: !0, keywords: "None" },
+              ],
+            },
+            { className: "meta", begin: /^[\t ]*@/, end: /$/ },
+            { begin: /\b(print|exec)\(/ },
+          ],
+        }
+      );
+    };
+  })(),
+);
diff --git a/docs/flake-parts-docs/intro-continued.md b/docs/flake-parts-docs/intro-continued.md
new file mode 100644
index 000000000..e398c97d4
--- /dev/null
+++ b/docs/flake-parts-docs/intro-continued.md
@@ -0,0 +1,7 @@
+<!-- prefaced by the README intro -->
+
+# This documentation
+
+You can find guides and the options reference in the menu (top left).
+
+A site wide search is available by typing `s`.
diff --git a/docs/flake-parts-docs/module-arguments.md b/docs/flake-parts-docs/module-arguments.md
new file mode 100644
index 000000000..e5f47c155
--- /dev/null
+++ b/docs/flake-parts-docs/module-arguments.md
@@ -0,0 +1,211 @@
+# Module Arguments
+
+The module system allows modules and submodules to be defined using plain attribute sets, or functions that return attribute sets.
+When a module is a function, the module system and flake-parts pass various attributes to it.
+These attributes are called _module arguments_.
+
+This page documents the available arguments.
+
+Note that if you use the `args@{ ... }` or `args:` syntax, you only receive the arguments you explicitly name in the function signature; see [below](#how-module-function-arguments-work) for details.
+
+# Top-level Module Arguments
+
+Top-level refers to the module passed to `mkFlake`, or any of the modules imported into it using `imports`.
+
+The standard module system arguments are available in all modules and submodules. These are chiefly `config`, `options`, `lib`.
+
+## `getSystem`
+
+A function from [system](./system.md) string to the `config` of the appropriate `perSystem`.
+
+## `moduleWithSystem`
+
+A function that brings the `perSystem` module arguments.
+This allows a module to reference the defining flake without introducing
+global variables.
+
+```nix
+{ moduleWithSystem, ... }:
+{
+  nixosModules.default = moduleWithSystem (
+    perSystem@{ config, ... }:  # NOTE: only explicitly named parameters will be in perSystem; see below
+    nixos@{ ... }:
+    {
+      services.foo.package = perSystem.config.packages.foo;
+      imports = [ ./nixos-foo.nix ];
+    }
+  );
+}
+```
+
+## `withSystem`
+
+Enter the scope of a system. Example:
+
+```nix
+{ withSystem, inputs, ... }:
+{
+  # perSystem = { ... }: { config.packages.hello = ...; };
+
+  flake.nixosConfigurations.foo = withSystem "x86_64-linux" (ctx@{ config, inputs', ... }:
+    inputs.nixpkgs.lib.nixosSystem {
+      # Expose `packages`, `inputs` and `inputs'` as module arguments.
+      # Use specialArgs permits use in `imports`.
+      # Note: if you publish modules for reuse, do not rely on specialArgs, but
+      # on the flake scope instead. See also https://flake.parts/define-module-in-separate-file.html
+      specialArgs = {
+        packages = config.packages;
+        inherit inputs inputs';
+      };
+      modules = [
+        # This module could be moved into a separate file; otherwise we might
+        # as well have used ctx.config.packages directly.
+        ({ config, lib, packages, pkgs, ... }: {
+          imports = [ ./nixos-configuration.nix ];
+          services.nginx.enable = true;
+          environment.systemPackages = [
+            # hello package defined in perSystem
+            packages.hello
+          ];
+        })
+      ];
+    });
+}
+```
+
+# `perSystem` Module Parameters
+
+## `pkgs`
+
+Default: `inputs.nixpkgs.legacyPackages.${system}`.
+
+Set via `config._module.args.pkgs`.
+
+Example:
+
+```nix
+perSystem = { pkgs, ... }: {
+  packages.hello = pkgs.hello;
+};
+```
+
+## `inputs'`
+
+The flake `inputs` parameter, but with `system` pre-selected. Note the last character of the name, `'`, pronounced _prime_.
+
+`inputs.foo.packages.x86_64-linux.hello` -> `inputs'.foo.packages.hello`
+
+`system` selection is handled by the extensible function [`perInput`](options/flake-parts.html#opt-perInput).
+
+Example:
+
+```nix
+perSystem = { inputs', ... }: {
+  packages.default = inputs'.foo.packages.bar;
+};
+```
+
+## `self'`
+
+The flake `self` parameter, but with `system` pre-selected.
+
+Example:
+
+```nix
+perSystem = { pkgs, self', ... }: {
+  packages.hello = pkgs.hello;
+  packages.default = self'.packages.hello;
+};
+```
+
+## `system`
+
+The [system](system.md) parameter, describing the architecture and platform of the host system (where the thing will run).
+
+Example:
+
+```nix
+perSystem = { system, ... }: {
+  packages.nixosDefaultPackages =
+    let nixos = inputs.nixpkgs.lib.nixosSystem {
+          modules = [ { nixpkgs.hostPlatform = system; } ];
+        };
+        checked = builtins.seq nixos.config.system.build.toplevel;
+       # I have no idea why you would want this, but you do you
+    in checked nixos.config.system.path;
+};
+```
+
+## How Module Function Arguments Work
+
+The Nix module system determines which arguments to pass to a module function by using `builtins.functionArgs`.
+This means only the parameters you explicitly name in your function signature will be available.
+
+### Examples
+
+**This doesn't capture all module arguments:**
+
+```nix
+perSystem =
+  # A perSystem definition is also a module
+  args: {
+    # args will NOT contain module arguments like pkgs, self', inputs', etc.
+    # despite being defined:
+    _module.args.pkgs = import ...;
+    packages.example = args.pkgs.hello;  # Error: attribute 'pkgs' missing
+  };
+```
+
+**This does work:**
+
+```nix
+perSystem = { pkgs, self', inputs', ... }: {
+  # Named arguments are available
+  packages.example = pkgs.hello;
+  packages.fromOther = inputs'.other-flake.packages.something;
+};
+```
+
+**This works, but is not recommended:**
+
+```nix
+perSystem = args@{ pkgs, self', inputs', ... }: {
+  # Not recommended, as the availability of `args` can lead to confusion
+  packages.example = args.pkgs.hello;
+  packages.fromOther = args.inputs'.other-flake.packages.something;
+};
+```
+
+### Obtaining All Module Arguments
+
+In the context of `perSystem`, you can obtain all module arguments using the internal option `allModuleArgs`:
+
+```nix
+perSystem = { config, ... }: {
+  # Access all perSystem module arguments
+  packages.example = config.allModuleArgs.pkgs.hello;
+
+  # This includes custom arguments defined with _module.args
+  packages.custom = config.allModuleArgs.myCustomArg;
+
+  # You can even access the entire set of module arguments
+  foo = config.allModuleArgs;
+};
+```
+
+`allModuleArgs` is available because flake-parts provides it for the `perSystem` submodule evaluation, similar to how it works with the `withSystem` function.
+
+This is not provided for the top level flake-parts configuration; only `perSystem`.
+
+### Rationale
+
+Nix evaluates the attribute set passed to a function like `args@{ foo, ... }` strictly (before returning the function body) in order to efficiently check the function call's argument, to make sure it's an attribute set, and that it has the listed attribtes, like `foo`.
+
+This means it needs to evaluate the argument before returning the function body.
+However, the module system would face a circular dependency when passing the module arguments using a straightforward function call: it can't know all available module argument names until it has evaluated the modules, but it can't evaluate module functions without passing them their arguments.
+
+To solve this, the module system uses `builtins.functionArgs` to inspect what arguments a module function expects, and constructs the argument set accordingly. If a module argument is not defined in any module or `specialArgs`, the attribute for it is present, but instead of a value, evaluating it will throw an exception.
+
+In a normal Nix function invocation, an `args@` binding would bind to the original argument set, which, as discussed, is not the complete set of module arguments.
+
+Unfortunately, the module system cannot know whether such a binding is present in the function definition, so it cannot warn about this potential issue.
diff --git a/docs/flake-parts-docs/overlays.md b/docs/flake-parts-docs/overlays.md
new file mode 100644
index 000000000..eb3b4f5e3
--- /dev/null
+++ b/docs/flake-parts-docs/overlays.md
@@ -0,0 +1,109 @@
+# Overlays
+
+Overlays in Nixpkgs allow the customization of the entire package set in a consistent manner. For example, if you set a library's attribute in an overlay, this change will be applied to all packages that previously depended on that attribute. This is in contrast with the way the Flake `packages` attribute works. Such definitions do not feed back into the Nixpkgs package set.
+
+Advantages of overlays:
+
+- The original attribute won't be around anymore. This almost guarantees that
+  the original value won't be used anywhere else.
+- The dependencies are more coherent, resulting in fewer "diamond dependency" conflicts
+
+Advantages of the flake `packages` attribute without `inputs.<input>.follows`:
+
+- A package definition won't interfere with other packages.
+- The packages will be used with the dependencies that its CI built it with, resulting in fewer build problems.
+
+Advantages of the flake `packages` attribute with `inputs.<input>.follows`:
+
+- A package definition won't interfere with other packages.
+- The dependencies are more coherent, resulting in fewer "diamond dependency" conflicts
+
+Neither option is perfect.
+
+## Consuming an overlay
+
+Flake parts does not yet come with an endorsed module that initializes the `pkgs` argument.
+
+You may initialize it manually; for example:
+
+```nix
+perSystem = { system, ... }: {
+  _module.args.pkgs = import inputs.nixpkgs {
+    inherit system;
+    overlays = [
+      inputs.foo.overlays.default
+      (final: prev: {
+        # ... things you need to patch ...
+      })
+    ];
+    config = { };
+  };
+};
+```
+
+## Defining an overlay
+
+While overlays are about packages, and therefore dependent on the choice of `system`, they are not defined under a system attribute. Instead they are in a top level attribute.
+
+The reason for this is that they are conceptually defined as a function of not just `system`, but of a package set that includes `system`. Putting them in a `${system}` attribute would be conceptually redundant, and it would bother users of the overlay.
+
+If an overlay needs a system string, it should usually reach for `prev.stdenv.hostPlatform.system`.
+
+```
+final: prev: {
+  systemStringFile = prev.writeText "system-string"
+    prev.stdenv.hostPlatform.system;
+}
+```
+
+A manually defined overlay (more on automation later), can make use of `perSystem` as follows:
+
+```nix
+{ withSystem, ... }: {
+  flake.overlays.my-overlay = final: prev:
+    withSystem prev.stdenv.hostPlatform.system (
+      # perSystem parameters. Note that perSystem does not use `final` or `prev`.
+      { config, ... }: {
+        my-package = config.packages.my-package;
+      });
+}
+```
+
+Note that such a usage of `perSystem` may introduce packages from the locked inputs of the overlay-defining flake into a completely different version of Nixpkgs. This may or may not be desirable as discussed in the introduction.
+
+A more integrated method that repurpose the `pkgs` module argument in `perSystem` is available in the [`easyOverlay`] module, which is the topic of the next section.
+
+## An overlay for free with flake-parts
+
+While it is possible to define an [overlay](options/flake-parts.html#opt-flake.overlays) manually, flake-parts offers a module that derives an overlay from the `perSystem` module.
+
+Here's a flake module that defines `overlays.default` to an overlay of the shape `final: prev: { my-package = ...; }`.
+
+```nix
+{
+  imports = [
+    inputs.flake-parts.flakeModules.easyOverlay
+  ];
+  perSystem = { config, pkgs, final, ... }: {
+    overlayAttrs = {
+      inherit (config.packages) my-package;
+    };
+    packages.my-package = /* ... */;
+  };
+}
+```
+
+### Altered `perSystem` module arguments
+
+In the context of an overlay, the `pkgs` module argument is defined as the "previous" or "super" argument of an overlay.
+
+The `final` module argument is only defined when [`easyOverlay`] is imported. It is defined as the "final" or "self" argument. It is _also_ available outside the context of an `flake.overlays.default`, in which case its value is (also) equal to `pkgs` extended by the [`overlayAttrs`].
+
+## See also
+
+- [`easyOverlay`]
+- [`perSystem.overlayAttrs`]
+
+[`easyOverlay`]: options/flake-parts-easyOverlay.md
+[`overlayAttrs`]: options/flake-parts-easyOverlay.md#opt-perSystem.overlayAttrs
+[`perSystem.overlayAttrs`]: options/flake-parts-easyOverlay.md#opt-perSystem.overlayAttrs
diff --git a/docs/flake-parts-docs/system.md b/docs/flake-parts-docs/system.md
new file mode 100644
index 000000000..d1065277a
--- /dev/null
+++ b/docs/flake-parts-docs/system.md
@@ -0,0 +1,19 @@
+# Multi-platform: `system`
+
+In Nix, "system" generally refers to the cpu-os string, such as `"x86_64-linux"`.
+
+In Flakes specifically, these strings are used as attribute names, so that the
+Nix CLI can find a derivation for the right platform.
+
+Many things, such as packages, can exist on multiple systems. For these, use
+the [`perSystem`](options/flake-parts.html#opt-perSystem) submodule.
+
+Other things do not exist on multiple systems. Examples are the configuration
+of a specific machine, or the execution of a deployment. These are not
+written in `perSystem`, but in other top-level options, or directly into the
+flake outputs' top level (e.g. [`flake.nixosConfigurations`](options/flake-parts.html#opt-flake.nixosConfigurations)).
+
+Such top-level entities typically do need to read packages, etc that are defined
+in `perSystem`. Instead of reading them from `config.flake.packages.<system>.<name>`,
+it may be more convenient to bring all `perSystem` definitions for a system into
+scope, using [`withSystem`](module-arguments.html#withsystem).
diff --git a/docs/system76-home-manager-observations.md b/docs/system76-home-manager-observations.md
index 5c8bfced6..7a21b2e99 100644
--- a/docs/system76-home-manager-observations.md
+++ b/docs/system76-home-manager-observations.md
@@ -24,6 +24,7 @@ System76’s NixOS host does import the workstation bundle and the System76‑sp
 - A recursive sweep of `nixosConfigurations.system76._module.args.modules` finds no module originating from `modules/meta/nixos-role-helpers.nix` or `modules/meta/nixos-app-helpers.nix`; the base bundle still contains other meta contributors (docs, owner, nixpkgs-allowed-unfree), so the helper injection never enters the host evaluation, leaving both `_module.args.nixosRoleHelpers` and the `flake.lib.nixos` helper namespace unset.
 - Adding `modules/meta/nixos-helpers.nix` to import the helper modules ensures `_module.args.nixosRoleHelpers` and `_module.args.nixosAppHelpers` appear in base-only evaluation, and `modules/meta/nixos-roles-import.nix` now pulls `modules/roles/**` into the base aggregator. After those changes `config.flake.nixosModules.roles` finally exposes the first role (`ai-agents`), proving the aggregator is active—but the remaining roles still fail to load because their prerequisites (apps, window-manager modules, etc.) aren’t satisfied during the scaffold run.
 - Evaluating the full System76 stack still strips `_module.args` back to `{ extendModules, moduleType, pkgs }`; `config.home-manager` retains only `backupFileExtension`, `extraAppImports`, `extraSpecialArgs`, `sharedModules`, `useGlobalPkgs`, and `users`, so options like `enableLegacyProfileManagement`, `overwriteBackup`, `useUserPackages`, and `verbose` remain missing.
+- 2025-10-21 — Normalised the System76 import stage to unwrap import-tree payloads before the workstation checks run. Introduced `flattenImportTree` inside `modules/system76/imports.nix` so lookups such as `getModule "base"` and the role resolver see plain attrsets rather than `_type`/`content` stubs. `nix flake check --accept-flake-config` still halts with `Home Manager base module: expected flake.homeManagerModules.base to be available.`, and `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.flake.nixosModules'` continues to fail on `attribute 'lang' missing`, which shows the flattening step alone doesn’t surface the missing Home Manager glue.
 - The `_module.args` trace continues to show that the collapse happens at the `pre-system76` checkpoint. Because only one role successfully registers, `modules/system76/imports.nix` still fails to resolve `base` and other workstation roles (the helper falls back to `config.flake.nixosModules.roles`, which lacks those keys), preventing the base bundle—and thus the Home Manager glue—from executing.
 - Instrumenting the scaffold with `debug.roleProbe` now records every role module under `modules/roles`. Most files export a `flake.nixosModules.roles.<name>.imports` attrset and evaluate cleanly, while dotted roles (for example `roles.dev.clj`) land under nested paths that our probe flattens separately. Roles that fan out to language bundles (`dev-clj`, `dev-go`, `dev-py`, `dev-rs`) expect stubs under `flake.nixosModules.lang.*`, and desktop roles reach for `flake.nixosModules.window-manager.i3`. Until those namespaces are stubbed, the aggregator keeps collapsing to just `ai-agents`, so the helpers never expose additional role names to the workstation stack.
 - Added a dedicated `stubModule` to the scaffold that pre-populates `flake.nixosModules.apps`, `flake.nixosModules.lang`, and `flake.nixosModules."window-manager"` with real modules when available and inert lambdas otherwise. This prevents `nixos-app-helpers` and the desktop roles from crashing on missing lookups, but the flattened attrset at `config.flake.nixosModules.roles` still comes back empty—confirming that the roles import itself isn’t materialising yet, even though each role module evaluates successfully in isolation.
@@ -36,6 +37,11 @@ System76’s NixOS host does import the workstation bundle and the System76‑sp
 - Added `debug/flake-nixosModules-reproducer.nix` to isolate the failure: evaluating a single module that writes `config.flake.nixosModules.roles.xserver` reproduces the missing-option error, while prepending a minimal stub module (`options.flake.nixosModules = …`) lets the same evaluation succeed. This confirms the harness simply needs the option defined before the roles run; the remaining work is ensuring the real bootstrap executes during System76 evaluation instead of relying on ad-hoc stubs.
 - Reintroducing the manual `modules/meta/flake-output.nix` import inside `modules/meta/nixos-helpers.nix` remains necessary today. Without it, the meta aggregator (`nixos-roles-preload` → `nixos-role-helpers` → `nixos-app-helpers`) crashes immediately because no one has defined the `flake.*` option namespace yet. With the import restored, the evaluation makes it past the helpers and fails later in `modules/roles/xserver.nix`, indicating the bootstrap simply moves the symptom downstream rather than fixing the underlying requirement to seed `flake.*` before either stack runs.
 - Reordering the helper list so `flake-output.nix` runs before `nixos-roles-preload.nix` removes that early assignment, but the base harness continues to fail: the structured trace still reports `error: The option 'flake.nixosModules' does not exist` because the harness never imports the flake-level bootstrap emitted by `inputs.import-tree`. In the real flake, `/nix/store/*/modules/nixosModules.nix` registers the option; without that module in the harness, only the role definitions remain, and the lookup still throws.
+- Replaced the temporary System76-only bootstrap with two structural fixes: (1) `inputs.import-tree` now pipes through a reorder function so `modules/meta/flake-output.nix`, `nixos-helpers.nix`, and the helper stack run before any role touches `flake.*`; (2) `modules/meta/nixos-helpers.nix` imports the upstream `flake-parts/modules/nixosModules.nix` during NixOS evaluation, wiring in the official `mkSubmoduleOptions` schema. After these changes `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'` no longer throws `error: The option 'flake.nixosModules' does not exist`—the evaluation now proceeds to the expected Home Manager failure (`flake.homeManagerModules.base` missing).
+- Added a System76-scoped bootstrap (`modules/system76/flake-nixosModules-bootstrap.nix`) and passed `system76NeedsFlakeBootstrap = true` via the host’s `nixosSystem` `specialArgs`, so only the System76 evaluation defines `options.flake.nixosModules`. This keeps the flake-level `nixosModules` output using the upstream schema while unblocking the host import order. `nix flake check --accept-flake-config` now progresses to the Home Manager failure, and `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'` reports the same `flake.homeManagerModules.base` error as before—confirming `_module.check` remains enabled and we’re no longer silencing the missing-option check.
+- Verifying the new order with
+  `nix eval --impure --accept-flake-config --json --expr 'let flake = builtins.getFlake (toString ./.); lib = flake.inputs.nixpkgs.lib; preludeSuffixes = [ "/modules/meta/flake-output.nix" "/modules/meta/nixos-roles-preload.nix" "/modules/meta/nixos-helpers.nix" "/modules/meta/nixos-role-helpers.nix" "/modules/meta/nixos-app-helpers.nix" "/modules/meta/nixos-roles-import.nix" ]; pathOf = value: if builtins.isAttrs value && value ? _file then value._file else if builtins.isPath value then toString value else if builtins.isString value then value else ""; orderedPrelude = paths: builtins.concatLists (map (suffix: builtins.filter (module: lib.hasSuffix suffix (pathOf module)) paths) preludeSuffixes); reorderPaths = paths: let prelude = orderedPrelude paths; preludeKeys = map pathOf prelude; rest = builtins.filter (module: let key = pathOf module; in !(lib.elem key preludeKeys)) paths; in prelude ++ rest; reorderModule = paths: { imports = reorderPaths paths; }; adjusted = (flake.inputs.import-tree.withLib lib).pipeTo reorderModule ./modules; in lib.take 10 (map (x: if builtins.isAttrs x then (x._file or "<lambda>") else x) adjusted.imports)'`
+  shows the first six entries now belong to `modules/meta/{flake-output,nixos-roles-preload,nixos-helpers,nixos-role-helpers,nixos-app-helpers,nixos-roles-import}.nix`, confirming the helper prelude executes before any application module.
 
 ## Consequence
 
@@ -52,3 +58,10 @@ A dedicated scaffold (`debug/system76-home-manager-scaffold.nix`) now recreates
 1. Trace exactly where `_module.args.nixosRoleHelpers` is supposed to be injected (the meta helpers module) and confirm whether import-tree skips it or a later module overwrites `_module.args`.
 2. Verify the evaluation context around `modules/workstation.nix` once the helpers are present—ensure `resolveRole "base"` pulls in the glue and that `config.home-manager` retains the full attrset.
 3. Only after helpers flow, revisit the `home-manager.sharedModules` merge conflict to make sure the overlays still compose cleanly and no new regressions appear.
+
+- 2025-10-22 — Relaxed the guard in `modules/home-manager/nixos.nix` so any `flake.homeManagerModules.base` definition with an `imports` list (even when those entries are lambdas) counts as “real”. Ran `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`; it still aborts with `Home Manager base module: expected flake.homeManagerModules.base to be available.`, implying the base module disappears earlier in the System76 sequence rather than being rejected by the guard.
+- 2025-10-22 — Replayed the scaffold prefix to isolate where the Home Manager glue disappears. `nix eval --impure --accept-flake-config --json --expr 'let flake = builtins.getFlake (toString ./.) ; lib = flake.inputs.nixpkgs.lib; scaffold = import ./debug/system76-home-manager-scaffold.nix { inherit flake lib; }; prefix = lib.take 4 scaffold.modules; eval = lib.evalModules { modules = prefix; specialArgs = scaffold.specialArgs; }; in eval.config.debug.flakeTrace'` reports `debug.flakeTrace.pre-system76.homeManagerModules = "<empty>"` even though `nixosModules` still lists the full base catalogue, so the namespace is gone before any System76 import runs. Evaluating the scaffold with `[ scaffoldModule, stubModule, firstModule ]` via `nix eval --impure --accept-flake-config --json --expr 'let flake = builtins.getFlake (toString ./.) ; lib = flake.inputs.nixpkgs.lib; scaffold = import ./debug/system76-home-manager-scaffold.nix { inherit flake lib; }; modules = [ scaffold.scaffoldModule scaffold.stubModule scaffold.firstModule ]; eval = lib.evalModules { inherit modules; specialArgs = scaffold.specialArgs; }; in { hm = eval.config.flake.homeManagerModules or {}; nx = builtins.attrNames (eval.config.flake.nixosModules or {}); }'` shows the base keys (`apps`, `base`, `roles`, etc.) are present while `hm` stays `{}`, confirming the collector never hydrates the Home Manager namespace during the meta prelude.
+- 2025-10-22 — Attempted Option A fix in `modules/system76/imports.nix`: preferentially pulled `nixosModules`/`homeManagerModules` from `inputs.self` and, when those remained empty, evaluated a bootstrap stack (`flake-nixosModules-bootstrap.nix` + meta collectors) to seed `flake.homeManagerModules`. The new trace still reports `pre-system76` as `<empty>` and `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'` continues to fail with `Home Manager base module: expected flake.homeManagerModules.base to be available.`, so the fallback injector is not yet feeding the System76 stack.
+- 2025-10-22 — Instrumented `modules/system76/imports.nix` to trace every `getModule`/`getRoleModule` call. During the failing eval (`nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`) each lookup reports Home Manager keys `apps, base, context7Secrets, gui, r2Secrets` still present, even after the role helpers run. The namespace only vanishes after control leaves the System76 aggregator, so the wipe must come from a downstream import (or a later merge) rather than the System76 module itself.
+- 2025-10-22 — Added stepwise traces across `modules/system76/imports.nix`; every lookup (`getModule`, `getRoleModule`, etc.) still sees `flake.homeManagerModules` populated (`apps`, `base`, `context7Secrets`, `gui`, `r2Secrets`). After relaxing the Home Manager guard to unwrap `mkOverride` payloads, the evaluation moves past the old missing-base error and now stops at `home-manager.users.vx.apps` being undefined. This confirms the namespace survives the System76 assembly and highlights the next gap is the Home Manager option tree rather than the flake namespace.
+- 2025-10-22 — Addressed the "Home Manager base module" guard by unwrapping the collected override. `modules/home-manager/nixos.nix` now expands `flake.homeManagerModules.base.imports` directly (rather than handing the wrapper to Home Manager), which made `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'` advance to the next failure. The namespace stays intact all the way through System76; the current blocker is that Home Manager lacks option stubs for `home-manager.users.<owner>.apps` and related keys.
diff --git a/flake.nix b/flake.nix
index 09e3b247d..77cd91219 100644
--- a/flake.nix
+++ b/flake.nix
@@ -175,9 +175,50 @@
 
   outputs =
     inputs:
+    let
+      flakeLib = inputs.nixpkgs.lib;
+      importTree = inputs.import-tree.withLib flakeLib;
+      preludeSuffixes = [
+        "/modules/meta/flake-output.nix"
+        "/modules/meta/nixos-roles-preload.nix"
+        "/modules/meta/nixos-helpers.nix"
+        "/modules/meta/nixos-role-helpers.nix"
+        "/modules/meta/nixos-app-helpers.nix"
+        "/modules/meta/nixos-roles-import.nix"
+      ];
+      pathOf =
+        value:
+        if builtins.isAttrs value && value ? _file then
+          value._file
+        else if builtins.isPath value then
+          toString value
+        else if builtins.isString value then
+          value
+        else
+          "";
+      orderedPrelude =
+        paths:
+        builtins.concatLists (
+          map (
+            suffix: builtins.filter (module: flakeLib.hasSuffix suffix (pathOf module)) paths
+          ) preludeSuffixes
+        );
+      reorderPaths =
+        paths:
+        let
+          prelude = orderedPrelude paths;
+          preludeKeys = map pathOf prelude;
+          isPreludeKey = key: flakeLib.elem key preludeKeys;
+          rest = builtins.filter (module: !(isPreludeKey (pathOf module))) paths;
+        in
+        prelude ++ rest;
+      reorderModule = paths: {
+        imports = reorderPaths paths;
+      };
+    in
     inputs.flake-parts.lib.mkFlake { inherit inputs; } {
       imports = [
-        (inputs.import-tree ./modules)
+        (importTree.pipeTo reorderModule ./modules)
       ];
 
       systems = [
diff --git a/modules/home-manager/nixos.nix b/modules/home-manager/nixos.nix
index b35b9aa8c..4de3da5d8 100644
--- a/modules/home-manager/nixos.nix
+++ b/modules/home-manager/nixos.nix
@@ -15,73 +15,74 @@ builtins.trace "hm.nixos entry" {
         description = "Additional Home Manager app keys appended to the default app list.";
       };
 
-      config.home-manager = {
-        useGlobalPkgs = true;
-        extraSpecialArgs = {
-          hasGlobalPkgs = true;
-          inherit inputs;
-        };
-        backupFileExtension = "hm.bk";
-
-        users.${
-          let
-            flakeAttrs = config.flake or { };
-            ownerMeta = lib.attrByPath [ "lib" "meta" "owner" ] { } flakeAttrs;
-            fallbackOwnerName =
-              let
-                usersAttrs = config.users.users or { };
-                normalUsers = lib.filterAttrs (_: u: (u.isNormalUser or false)) usersAttrs;
-              in
-              if normalUsers != { } then lib.head (lib.attrNames normalUsers) else null;
-          in
-          ownerMeta.username or (
-            if fallbackOwnerName != null then
-              fallbackOwnerName
-            else
-              throw "Home Manager base module: unable to determine owner username (set config.flake.lib.meta.owner.username or define a normal user)."
-          )
-        }.imports =
-          let
-            moduleArgs = config._module.args or { };
-            inputsArg = moduleArgs.inputs or { };
-            flakeAttrs = config.flake or { };
-            hmModulesFromConfig = lib.attrByPath [ "homeManagerModules" ] { } flakeAttrs;
-            hmModulesFromInputs = lib.attrByPath [ "self" "homeManagerModules" ] { } inputsArg;
-            hmModules =
-              let
-                combined =
-                  assert (
-                    lib.hasAttrByPath [ "homeManagerModules" "base" ] flakeAttrs
-                    || lib.hasAttrByPath [ "self" "homeManagerModules" "base" ] inputsArg
-                  );
-                  if hmModulesFromConfig != { } then hmModulesFromConfig else hmModulesFromInputs;
-              in
-              builtins.trace (
-                "hm.nixos hmModules keys: "
-                + (if combined != { } then lib.concatStringsSep ", " (lib.attrNames combined) else "<empty>")
-              ) combined;
-            hmApps = hmModules.apps or { };
-            hasApp = name: lib.hasAttr name hmApps;
-            getApp =
-              name:
-              if hasApp name then
-                lib.getAttr name hmApps
+      config.home-manager =
+        let
+          flakeAttrs = config.flake or { };
+          ownerMeta = lib.attrByPath [ "lib" "meta" "owner" ] { } flakeAttrs;
+          usersAttrs = config.users.users or { };
+          normalUsers = lib.filterAttrs (_: u: (u.isNormalUser or false)) usersAttrs;
+          ownerName =
+            ownerMeta.username or (
+              if normalUsers != { } then
+                lib.head (lib.attrNames normalUsers)
               else
-                throw "Unknown Home Manager app '${name}' referenced by base imports";
-            defaultAppImports = [
-              "codex"
-              "bat"
-              "eza"
-              "fzf"
-              "ghq-mirror"
-              "kitty"
-              "alacritty"
-              "wezterm"
-            ];
-            extraAppImports = lib.attrByPath [ "home-manager" "extraAppImports" ] [ ] config;
-            allAppImports = defaultAppImports ++ extraAppImports;
-          in
-          [
+                throw "Home Manager base module: unable to determine owner username (set config.flake.lib.meta.owner.username or define a normal user)."
+            );
+          moduleArgs = config._module.args or { };
+          inputsArg = moduleArgs.inputs or { };
+          hmModulesFromConfig = lib.attrByPath [ "homeManagerModules" ] { } flakeAttrs;
+          hmModulesFromInputs = lib.attrByPath [ "self" "homeManagerModules" ] { } inputsArg;
+          hmModules =
+            let
+              combined =
+                assert (
+                  lib.hasAttrByPath [ "homeManagerModules" "base" ] flakeAttrs
+                  || lib.hasAttrByPath [ "self" "homeManagerModules" "base" ] inputsArg
+                );
+                if hmModulesFromConfig != { } then hmModulesFromConfig else hmModulesFromInputs;
+            in
+            builtins.trace (
+              "hm.nixos hmModules keys: "
+              + (if combined != { } then lib.concatStringsSep ", " (lib.attrNames combined) else "<empty>")
+            ) combined;
+          configBase = lib.attrByPath [ "base" ] hmModules null;
+          baseModuleImports =
+            if configBase == null then
+              throw "Home Manager base module: expected flake.homeManagerModules.base to be available."
+            else if configBase ? imports then
+              configBase.imports
+            else if configBase ? content && configBase.content ? imports then
+              configBase.content.imports
+            else
+              [ configBase ];
+          hmApps = hmModules.apps or { };
+          _hmAppsTrace = builtins.trace (
+            "hm.nixos hmApps: " + (if hmApps == null then "null" else builtins.typeOf hmApps)
+          ) null;
+          hasApp = name: lib.hasAttr name hmApps;
+          getApp =
+            name:
+            if hasApp name then
+              lib.getAttr name hmApps
+            else
+              throw "Unknown Home Manager app '${name}' referenced by base imports";
+          defaultAppImports = [
+            "codex"
+            "bat"
+            "eza"
+            "fzf"
+            "ghq-mirror"
+            "kitty"
+            "alacritty"
+            "wezterm"
+          ];
+          extraAppImports = lib.attrByPath [ "home-manager" "extraAppImports" ] [ ] config;
+          allAppImports = defaultAppImports ++ extraAppImports;
+          appModulesRaw = map getApp allAppImports;
+          guiModule = lib.attrByPath [ "gui" ] hmModules null;
+          context7SecretsModule = lib.attrByPath [ "context7Secrets" ] hmModules null;
+          r2SecretsModule = lib.attrByPath [ "r2Secrets" ] hmModules null;
+          importsList = [
             inputs.sops-nix.homeManagerModules.sops
             (
               { osConfig, ... }:
@@ -89,16 +90,25 @@ builtins.trace "hm.nixos entry" {
                 home.stateVersion = osConfig.system.stateVersion;
               }
             )
-            (lib.attrByPath [ "base" ] hmModules (
-              throw "Home Manager base module: expected flake.homeManagerModules.base to be available."
-            ))
-            # Wire R2 sops-managed env by default (guarded on secrets/r2.env presence)
-            (lib.attrByPath [ "r2Secrets" ] hmModules { })
-            # Provide Context7 API key via sops when available
-            (lib.attrByPath [ "context7Secrets" ] hmModules { })
           ]
-          ++ map getApp allAppImports;
-      };
+          ++ baseModuleImports
+          ++ [
+            (if r2SecretsModule != null then r2SecretsModule else { })
+            (if context7SecretsModule != null then context7SecretsModule else { })
+          ]
+          ++ appModulesRaw;
+          appsForUsers = hmModules.apps or { };
+        in
+        {
+          useGlobalPkgs = true;
+          extraSpecialArgs = {
+            hasGlobalPkgs = true;
+            inherit inputs;
+          };
+          backupFileExtension = "hm.bk";
+          users.${ownerName}.imports = importsList;
+        };
+
     };
   };
 }
diff --git a/modules/meta/nixos-helpers.nix b/modules/meta/nixos-helpers.nix
index 0c1656428..b51c5a743 100644
--- a/modules/meta/nixos-helpers.nix
+++ b/modules/meta/nixos-helpers.nix
@@ -1,7 +1,8 @@
-_: {
+{ ... }:
+{
   flake.nixosModules.base.imports = [
     ./flake-output.nix
-    ./nixos-roles-preload.nix
+    ./nixos-home-manager-collect.nix
     ./nixos-role-helpers.nix
     ./nixos-app-helpers.nix
   ];
diff --git a/modules/meta/nixos-home-manager-collect.nix b/modules/meta/nixos-home-manager-collect.nix
new file mode 100644
index 000000000..a63a16417
--- /dev/null
+++ b/modules/meta/nixos-home-manager-collect.nix
@@ -0,0 +1,31 @@
+{ lib, ... }:
+let
+  homeDir = ./../home;
+  homeManagerDir = ./../home-manager;
+  hmAppsDir = ./../hm-apps;
+
+  listFiles =
+    dir:
+    let
+      entries = builtins.readDir dir;
+    in
+    builtins.filter (name: entries.${name} == "regular" && lib.hasSuffix ".nix" name) (
+      builtins.attrNames entries
+    );
+
+  importFiles = dir: names: map (name: import (dir + "/${name}")) names;
+
+  homeModules = importFiles homeDir (listFiles homeDir);
+  homeManagerModules = importFiles homeManagerDir (
+    builtins.filter (name: name != "checks.nix") (listFiles homeManagerDir)
+  );
+  hmAppModules = importFiles hmAppsDir (listFiles hmAppsDir);
+
+  baseImports = homeModules ++ homeManagerModules ++ hmAppModules;
+in
+{
+  flake.homeManagerModules.base = lib.mkOverride 1200 {
+    _file = "nixos-home-manager-collect";
+    imports = baseImports;
+  };
+}
diff --git a/modules/meta/nixos-roles-import.nix b/modules/meta/nixos-roles-import.nix
deleted file mode 100644
index 45903a20e..000000000
--- a/modules/meta/nixos-roles-import.nix
+++ /dev/null
@@ -1,6 +0,0 @@
-{ inputs, ... }:
-{
-  flake.nixosModules.base.imports = [
-    (inputs.import-tree ./../roles)
-  ];
-}
diff --git a/modules/meta/nixos-roles-preload.nix b/modules/meta/nixos-roles-preload.nix
deleted file mode 100644
index e2ffa26b4..000000000
--- a/modules/meta/nixos-roles-preload.nix
+++ /dev/null
@@ -1,19 +0,0 @@
-{
-  inputs ? { },
-  self ? null,
-  lib,
-  ...
-}:
-let
-  resolvedSelf =
-    if self != null then
-      self
-    else if inputs ? self then
-      inputs.self
-    else
-      builtins.getFlake (toString ../..);
-  modules = resolvedSelf.nixosModules or { };
-in
-{
-  config.flake.nixosModules = lib.mkDefault modules;
-}
diff --git a/modules/system76/flake-nixosModules-bootstrap.nix b/modules/system76/flake-nixosModules-bootstrap.nix
new file mode 100644
index 000000000..19a1ab926
--- /dev/null
+++ b/modules/system76/flake-nixosModules-bootstrap.nix
@@ -0,0 +1,20 @@
+{ lib, ... }@args:
+let
+  flag = (args ? system76NeedsFlakeBootstrap) && args.system76NeedsFlakeBootstrap;
+in
+if flag then
+  {
+    options.flake.nixosModules = lib.mkOption {
+      type = lib.types.lazyAttrsOf lib.types.deferredModule;
+      default = { };
+      apply = lib.mapAttrs (
+        name: value: {
+          _file = "flake.nixosModules.${name}";
+          imports = [ value ];
+        }
+      );
+      description = "NixOS modules published under flake.nixosModules.";
+    };
+  }
+else
+  { }
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index ff5b40a96..5fea5c123 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -5,10 +5,123 @@
   ...
 }:
 let
-  flake = config.flake; # or { };
-  nixosModules = flake.nixosModules; # or { };
+  flake = if config ? flake then config.flake else { };
+  selfFlake = config._module.args.self or inputs.self or null;
+  moduleNamespace =
+    attrs: name:
+    let
+      direct = lib.hasAttr name attrs;
+      content = lib.hasAttrByPath [ "content" name ] attrs;
+      nestedBase =
+        lib.hasAttrByPath [ "content" "content" name ] attrs
+        && lib.hasAttrByPath [ "content" name "imports" ] attrs.content;
+      _ = builtins.trace (
+        "system76 moduleNamespace "
+        + name
+        + ": "
+        + (if direct then "direct " else "")
+        + (if content then "content " else "")
+        + (if nestedBase then "nested " else "")
+      ) null;
+    in
+    direct || content || nestedBase;
+  flakeNixosModulesBootstrap = import ./flake-nixosModules-bootstrap.nix;
+  fallbackEval = lib.evalModules {
+    modules = [
+      flakeNixosModulesBootstrap
+      (import ./../meta/flake-output.nix)
+      (import ./../meta/nixos-home-manager-collect.nix)
+      (import ./../meta/nixos-role-helpers.nix)
+      (import ./../meta/nixos-app-helpers.nix)
+    ];
+    specialArgs = {
+      inherit lib inputs;
+      flake = flake;
+      self = if selfFlake != null then selfFlake else { };
+      system76NeedsFlakeBootstrap = true;
+    };
+  };
+  fallbackNixosModules = fallbackEval.config.flake.nixosModules or { };
+  fallbackHomeManagerModules = fallbackEval.config.flake.homeManagerModules or { };
+  nixosModulesFromConfig = flake.nixosModules or { };
+  nixosModulesFromSelf = if selfFlake != null then (selfFlake.nixosModules or { }) else { };
+  nixosModules =
+    if nixosModulesFromConfig != { } && moduleNamespace nixosModulesFromConfig "base" then
+      nixosModulesFromConfig
+    else if nixosModulesFromSelf != { } && moduleNamespace nixosModulesFromSelf "base" then
+      nixosModulesFromSelf
+    else
+      fallbackNixosModules;
+  _nixosTrace = builtins.trace (
+    "system76 nixos modules keys: "
+    + (
+      if nixosModulesFromConfig != { } then
+        builtins.concatStringsSep ", " (builtins.attrNames nixosModulesFromConfig)
+      else
+        "<empty>"
+    )
+  ) null;
+  homeManagerModulesFromConfig = flake.homeManagerModules or { };
+  homeManagerModulesFromSelf =
+    if selfFlake != null then (selfFlake.homeManagerModules or { }) else { };
+  _hmConfigTypeTrace = builtins.trace (
+    "system76 hmModulesFromConfig keys: "
+    + (
+      if homeManagerModulesFromConfig == { } then
+        "<empty>"
+      else
+        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModulesFromConfig)
+    )
+  ) null;
+  _hmConfigTrace = builtins.trace (
+    "system76 hm config has base: "
+    + (
+      if homeManagerModulesFromConfig != { } && moduleNamespace homeManagerModulesFromConfig "base" then
+        "yes"
+      else
+        "no"
+    )
+  ) null;
+  homeManagerModules =
+    if homeManagerModulesFromConfig != { } && moduleNamespace homeManagerModulesFromConfig "base" then
+      homeManagerModulesFromConfig
+    else if homeManagerModulesFromSelf != { } && moduleNamespace homeManagerModulesFromSelf "base" then
+      homeManagerModulesFromSelf
+    else
+      fallbackHomeManagerModules;
+  _hmTrace = builtins.trace (
+    "system76 hm modules keys: "
+    + (
+      if homeManagerModules == { } then
+        "<empty>"
+      else
+        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
+    )
+  ) null;
+  _hmFinalTrace = builtins.trace (
+    "system76 hm keys before returning module: "
+    + (
+      if homeManagerModules == { } then
+        "<empty>"
+      else
+        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
+    )
+  ) null;
   hasModule = name: lib.hasAttr name nixosModules;
-  getModule = name: if hasModule name then lib.getAttr name nixosModules else null;
+  getModule =
+    name:
+    let
+      hmKeys =
+        if homeManagerModules == { } then
+          "<empty>"
+        else
+          builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules);
+      messagePrefix = "system76 getModule(" + name + ") hm keys: " + hmKeys + " -> ";
+    in
+    if hasModule name then
+      builtins.trace (messagePrefix + "hit") (lib.getAttr name nixosModules)
+    else
+      builtins.trace (messagePrefix + "miss") null;
   roleHelpers =
     (config.flake.lib.nixos.roles or { }) // (config._module.args.nixosRoleHelpers or { });
   getRoleModule =
@@ -16,11 +129,18 @@ let
     let
       getRole = roleHelpers.getRole or (_: null);
       roleValue = getRole name;
+      hmKeys =
+        if homeManagerModules == { } then
+          "<empty>"
+        else
+          builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules);
     in
     if roleValue != null then
-      roleValue
+      builtins.trace ("system76 getRoleModule(" + name + ") hm keys: " + hmKeys + " -> helper") roleValue
     else if lib.hasAttrByPath [ "roles" name ] nixosModules then
-      lib.getAttrFromPath [ "roles" name ] nixosModules
+      builtins.trace ("system76 getRoleModule(" + name + ") hm keys: " + hmKeys + " -> flake") (
+        lib.getAttrFromPath [ "roles" name ] nixosModules
+      )
     else
       throw (
         "system76 host requires role " + name + " but it was not found in helpers or flake.nixosModules"
@@ -41,32 +161,58 @@ let
   ];
   workstationModule = getModule "workstation";
   baseModule = getModule "base";
-  flakeNixosModulesBootstrap = import ./flake-nixosModules-bootstrap.nix;
+  _baseTrace = builtins.trace (
+    "system76 baseModule present: " + (if baseModule == null then "no" else "yes")
+  ) null;
   flakeInitModule = _: {
     flake = lib.mkDefault { };
   };
+  traceModule =
+    name: module:
+    builtins.trace (
+      "system76 baseModules includes " + name + ": " + (if module == null then "null" else "set")
+    ) module;
   baseModulesRaw = [
     flakeNixosModulesBootstrap
     flakeInitModule
-    baseModule
-    inputs.nixos-hardware.nixosModules.system76
-    inputs.nixos-hardware.nixosModules.system76-darp6
-    (getModule "packages")
-    workstationModule
-    (getModule "system76-support")
-    (getModule "security")
-    (getModule "hardware-lenovo-y27q-20")
-    (getModule "duplicati-r2")
-    (getModule "virt")
+    (traceModule "base" baseModule)
+    (traceModule "inputs.hw.system76" inputs.nixos-hardware.nixosModules.system76)
+    (traceModule "inputs.hw.system76-darp6" inputs.nixos-hardware.nixosModules.system76-darp6)
+    (traceModule "packages" (getModule "packages"))
+    (traceModule "workstation" workstationModule)
+    (traceModule "system76-support" (getModule "system76-support"))
+    (traceModule "security" (getModule "security"))
+    (traceModule "hardware-lenovo-y27q-20" (getModule "hardware-lenovo-y27q-20"))
+    (traceModule "duplicati-r2" (getModule "duplicati-r2"))
+    (traceModule "virt" (getModule "virt"))
   ];
   baseModules = lib.filter (module: module != null) baseModulesRaw;
+  _hmAfterBase = builtins.trace (
+    "system76 hm keys after baseModules: "
+    + (
+      if homeManagerModules == { } then
+        "<empty>"
+      else
+        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
+    )
+  ) null;
   virtualizationModules = lib.filter (module: module != null) (
-    map getVirtualizationModule [
-      "docker"
-      "libvirt"
-      "ovftool"
-      "vmware"
-    ]
+    map
+      (
+        name:
+        let
+          module = getVirtualizationModule name;
+        in
+        builtins.trace (
+          "system76 getVirtualizationModule(" + name + ") -> " + (if module == null then "null" else "set")
+        ) module
+      )
+      [
+        "docker"
+        "libvirt"
+        "ovftool"
+        "vmware"
+      ]
   );
   selfRevision =
     let
@@ -86,6 +232,16 @@ in
     _module.check = true;
     _module.args.inputs = lib.mkDefault inputs;
     _module.args.self = lib.mkDefault (inputs.self or null);
+    flake.homeManagerModules =
+      let
+        configHasBase =
+          homeManagerModulesFromConfig != { } && moduleNamespace homeManagerModulesFromConfig "base";
+      in
+      lib.mkIf (!configHasBase) (
+        lib.mkMerge [
+          fallbackHomeManagerModules
+        ]
+      );
     imports =
       baseModules
       ++ virtualizationModules

From 53f531979ccf23e39644a18a2fe062c1b99ee75b Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Thu, 23 Oct 2025 16:48:35 +0300
Subject: [PATCH 18/20] finally progress

---
 debug/flake-nixosModules-reproducer.nix    |  16 +-
 debug/system76-home-manager-scaffold.nix   |  34 +++-
 docs/flake-parts-docs/highlight.js         |   6 +-
 docs/flake-parts-docs/module-arguments.md  |   2 +-
 docs/system76-home-manager-events.md       |  98 ++++++++++++
 docs/system76-home-manager-observations.md |   2 +
 modules/hm-apps/claude-code.nix            |   1 +
 modules/hm-apps/espanso.nix                |  16 +-
 modules/hm-apps/starship.nix               |  21 +++
 modules/home-manager/nixos.nix             | 175 ++++++++++++++++++---
 modules/meta/flake-output.nix              |   8 +-
 modules/meta/nixos-helpers.nix             |   3 +-
 modules/roles/pentesting-devshell.nix      |  11 +-
 modules/system76/home-manager-apps.nix     |  34 +---
 modules/system76/imports.nix               | 151 ++++++++----------
 modules/system76/packages.nix              |   3 +
 modules/workstation.nix                    |  43 +----
 17 files changed, 409 insertions(+), 215 deletions(-)
 create mode 100644 docs/system76-home-manager-events.md
 create mode 100644 modules/hm-apps/starship.nix

diff --git a/debug/flake-nixosModules-reproducer.nix b/debug/flake-nixosModules-reproducer.nix
index bc30d43b0..20f3ab856 100644
--- a/debug/flake-nixosModules-reproducer.nix
+++ b/debug/flake-nixosModules-reproducer.nix
@@ -17,17 +17,15 @@ let
       config.flake.nixosModules = lib.mkDefault { };
     };
 
-  roleModule =
-    { lib, ... }:
-    {
-      config.flake.nixosModules.roles = {
-        xserver = {
-          imports = [
-            (_: { })
-          ];
-        };
+  roleModule = _: {
+    config.flake.nixosModules.roles = {
+      xserver = {
+        imports = [
+          (_: { })
+        ];
       };
     };
+  };
 
   evalWithoutStub = builtins.tryEval (
     lib.evalModules {
diff --git a/debug/system76-home-manager-scaffold.nix b/debug/system76-home-manager-scaffold.nix
index 0e60574db..7c99bed9f 100644
--- a/debug/system76-home-manager-scaffold.nix
+++ b/debug/system76-home-manager-scaffold.nix
@@ -462,6 +462,19 @@ let
         stubModule
         firstModule
       ];
+      basePrefixEvaluation = builtins.tryEval (
+        lib.evalModules {
+          modules = basePrefix;
+          inherit specialArgs;
+        }
+      );
+      baseSharedModulesCount =
+        if basePrefixEvaluation.success then
+          lib.length (
+            lib.attrByPath [ "config" "home-manager" "sharedModules" ] [ ] basePrefixEvaluation.value
+          )
+        else
+          0;
       moduleLabel =
         module:
         if lib.isAttrs module && module ? label then
@@ -482,16 +495,16 @@ let
               builtins.tryEval (
                 lib.evalModules {
                   modules = prefix;
-                  specialArgs = specialArgs;
+                  inherit specialArgs;
                 }
               )
             else
               {
                 success = false;
-                value = takeAttempt.value;
+                inherit (takeAttempt) value;
               };
         in
-        {
+        rec {
           step = n;
           importLabel =
             if takeAttempt.success then
@@ -511,6 +524,21 @@ let
               builtins.toString evalAttempt.value
             else
               null;
+          sharedModulesSnapshot =
+            if evalAttempt.success then
+              lib.attrByPath [ "config" "home-manager" "sharedModules" ] [ ] evalAttempt.value
+            else
+              [ ];
+          sharedModulesAsserted =
+            if evalAttempt.success then
+              let
+                sharedModulesCount = lib.length sharedModulesSnapshot;
+              in
+              lib.assertMsg (
+                sharedModulesCount > baseSharedModulesCount
+              ) "scaffold: expected sharedModules to grow beyond base prefix"
+            else
+              false;
         };
     in
     lib.genList (index: evaluate (index + 1)) limit;
diff --git a/docs/flake-parts-docs/highlight.js b/docs/flake-parts-docs/highlight.js
index 0d0098332..b6715ed3f 100644
--- a/docs/flake-parts-docs/highlight.js
+++ b/docs/flake-parts-docs/highlight.js
@@ -369,7 +369,7 @@ var hljs = (function () {
     const h = { disableAutodetect: !0, name: "Plain text", contains: [] };
     var f = {
       noHighlightRe: /^(no-?highlight)$/i,
-      languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i,
+      languageDetectRe: /\b(?:lang|language)-([\w-]+)\b/i,
       classPrefix: "hljs-",
       tabReplace: null,
       useBR: !1,
@@ -903,13 +903,13 @@ var hljs = (function () {
         (e.result = {
           language: a.language,
           re: a.relevance,
-          relavance: a.relevance,
+          relevance: a.relevance,
         }),
         a.second_best &&
           (e.second_best = {
             language: a.second_best.language,
             re: a.second_best.relevance,
-            relavance: a.second_best.relevance,
+            relevance: a.second_best.relevance,
           }));
     }
     const N = () => {
diff --git a/docs/flake-parts-docs/module-arguments.md b/docs/flake-parts-docs/module-arguments.md
index e5f47c155..61a751f87 100644
--- a/docs/flake-parts-docs/module-arguments.md
+++ b/docs/flake-parts-docs/module-arguments.md
@@ -199,7 +199,7 @@ This is not provided for the top level flake-parts configuration; only `perSyste
 
 ### Rationale
 
-Nix evaluates the attribute set passed to a function like `args@{ foo, ... }` strictly (before returning the function body) in order to efficiently check the function call's argument, to make sure it's an attribute set, and that it has the listed attribtes, like `foo`.
+Nix evaluates the attribute set passed to a function like `args@{ foo, ... }` strictly (before returning the function body) in order to efficiently check the function call's argument, to make sure it's an attribute set, and that it has the listed attributes, like `foo`.
 
 This means it needs to evaluate the argument before returning the function body.
 However, the module system would face a circular dependency when passing the module arguments using a straightforward function call: it can't know all available module argument names until it has evaluated the modules, but it can't evaluate module functions without passing them their arguments.
diff --git a/docs/system76-home-manager-events.md b/docs/system76-home-manager-events.md
new file mode 100644
index 000000000..52d7dccd9
--- /dev/null
+++ b/docs/system76-home-manager-events.md
@@ -0,0 +1,98 @@
+# System76 Home Manager Investigation – Key Events & Dependencies
+
+The following timeline distils the most relevant checkpoints captured in `docs/system76-home-manager-observations.md`. Each entry highlights what changed or was discovered, along with the commands, modules, or inputs that the step depended on.
+
+## Timeline
+
+- **Initial failure scan – undated baseline**
+  - **Finding:** `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager'` only returned `home-manager.extraAppImports`; `config.home-manager.users` was missing entirely.
+  - **Dependencies:** `modules/home-manager/nixos.nix` (no owner import executed); host evaluation lacked `_module.args.inputs` from `inputs.self`.
+  - **Impact:** Established that the Home Manager glue never ran and that upstream inputs were not in scope.
+
+- **Helper scope audit – undated baseline**
+  - **Finding:** `_module.args.nixosRoleHelpers` and `_module.args.nixosAppHelpers` were absent during the System76 evaluation, even though the base bundle contained meta modules.
+  - **Dependencies:** `modules/meta/nixos-role-helpers.nix`, `modules/meta/nixos-app-helpers.nix`, and the System76 import order defined in `modules/system76/imports.nix`.
+  - **Impact:** Confirmed the helper injection never reached the host evaluation, explaining missing role/application wiring.
+
+- **Meta helper reordering – undated baseline**
+  - **Finding:** Adding `modules/meta/nixos-helpers.nix` (along with role/app helpers) to the meta stack allowed `_module.args.nixosRoleHelpers` to appear during base-only evaluation and exposed `config.flake.nixosModules.roles.ai-agents`.
+  - **Dependencies:** `modules/meta/nixos-helpers.nix`, `modules/meta/nixos-roles-import.nix`; evaluation performed with the debug scaffold (`debug/system76-home-manager-scaffold.nix`).
+  - **Impact:** Demonstrated the aggregator works when helpers run early, but highlighted that downstream imports still clobbered Home Manager options.
+
+- **Import-tree ordering fix – 2025‑10‑22**
+  - **Finding:** Normalised System76’s import stage to unwrap import-tree payloads before the workstation checks. `modules/system76/imports.nix` now uses a flattened `config.flake.nixosModules` view, letting lookups like `getModule "workstation"` succeed.
+  - **Dependencies:** `modules/system76/imports.nix`, `inputs.import-tree`; evaluation verified via the scaffold and `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`.
+  - **Impact:** Eliminated earlier “missing option `flake.nixosModules`” errors and moved the investigation to Home Manager namespace issues.
+
+- **Home Manager guard relaxation – 2025‑10‑22**
+  - **Finding:** Adjusted `modules/home-manager/nixos.nix` to treat override-wrapped modules as valid base definitions. The evaluation advanced past the previous “Home Manager base module missing” guard.
+  - **Dependencies:** `modules/home-manager/nixos.nix`, `flake.homeManagerModules.base.imports`; tested with the System76 configuration eval command above.
+  - **Impact:** Exposed the next blocker—`home-manager.users.<owner>.apps` was undefined after the guard passed.
+
+- **GUI bundle deduplication – 2025‑10‑22**
+  - **Finding:** Flattening `flake.homeManagerModules.gui.imports` and reworking `_user-bundles.nix` removed the duplicate `gui.i3.lockCommand` definitions. Evaluation then stalled on the missing `home-manager.users.<owner>.apps` option.
+  - **Dependencies:** `_user-bundles.nix`, `modules/home-manager/nixos.nix`; validated with `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`.
+  - **Impact:** Confirmed that bundling logic needed a new compatibility strategy (either legacy shims or a different aggregation point).
+
+- **Plan revision (current work in progress)**
+  - **Finding:** Directly pushing flatten bundles into `home-manager.sharedModules` without recreating legacy options still triggers the missing-option error because the raw import-tree attrsets expect `home-manager.users.<owner>.apps` to exist.
+  - **Dependencies:** `modules/home-manager/nixos.nix` (flattening pipeline), System76 scaffold, evaluation command above.
+  - **Impact:** Steering the next iteration toward constructing a wrapper module that imports concrete modules only, avoiding any implicit redefinition of Home Manager option namespaces.
+
+## Cross-cutting Dependencies
+
+- **Evaluation commands**
+  - `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`
+  - `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager'`
+  - Scaffold-driven `lib.evalModules` routines in `debug/system76-home-manager-scaffold.nix`
+
+- **Key modules**
+  - `modules/system76/imports.nix` – controls import-tree order and helper availability.
+  - `modules/home-manager/nixos.nix` – gathers Home Manager modules, injects shared modules, and exposes owner configuration.
+  - Meta helpers: `modules/meta/nixos-helpers.nix`, `modules/meta/nixos-role-helpers.nix`, `modules/meta/nixos-app-helpers.nix`.
+
+These notes should make it easier to trace which change produced which effect without combing the full observations log. Update this file whenever new checkpoints land so it stays aligned with ongoing debugging.
+
+## Diagram
+
+```mermaid
+graph TD
+    A[Initial failure scan] --> B[Helper scope audit]
+    B --> C[Meta helper reordering]
+    C --> D[Import-tree ordering fix<br/>2025-10-22]
+    D --> E[Home Manager guard relaxation<br/>2025-10-22]
+    E --> F[GUI bundle deduplication<br/>2025-10-22]
+    F --> G[Plan revision<br/>(current work in progress)]
+
+    subgraph Commands & Tools
+      H[`nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`]
+      I[debug/system76-home-manager-scaffold.nix]
+    end
+
+    subgraph Module Dependencies
+      M1[modules/home-manager/nixos.nix]
+      M2[modules/system76/imports.nix]
+      M3[modules/meta/nixos-helpers.nix]
+      M4[modules/meta/nixos-role-helpers.nix]
+      M5[modules/meta/nixos-app-helpers.nix]
+    end
+
+    A --- H
+    A --- M1
+    B --- M3
+    B --- M4
+    B --- M5
+    B --- M2
+    C --- I
+    C --- M3
+    C --- M4
+    C --- M5
+    D --- M2
+    D --- H
+    E --- M1
+    E --- H
+    F --- M1
+    F --- H
+    G --- M1
+    G --- H
+```
diff --git a/docs/system76-home-manager-observations.md b/docs/system76-home-manager-observations.md
index 7a21b2e99..b603b749f 100644
--- a/docs/system76-home-manager-observations.md
+++ b/docs/system76-home-manager-observations.md
@@ -65,3 +65,5 @@ A dedicated scaffold (`debug/system76-home-manager-scaffold.nix`) now recreates
 - 2025-10-22 — Instrumented `modules/system76/imports.nix` to trace every `getModule`/`getRoleModule` call. During the failing eval (`nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'`) each lookup reports Home Manager keys `apps, base, context7Secrets, gui, r2Secrets` still present, even after the role helpers run. The namespace only vanishes after control leaves the System76 aggregator, so the wipe must come from a downstream import (or a later merge) rather than the System76 module itself.
 - 2025-10-22 — Added stepwise traces across `modules/system76/imports.nix`; every lookup (`getModule`, `getRoleModule`, etc.) still sees `flake.homeManagerModules` populated (`apps`, `base`, `context7Secrets`, `gui`, `r2Secrets`). After relaxing the Home Manager guard to unwrap `mkOverride` payloads, the evaluation moves past the old missing-base error and now stops at `home-manager.users.vx.apps` being undefined. This confirms the namespace survives the System76 assembly and highlights the next gap is the Home Manager option tree rather than the flake namespace.
 - 2025-10-22 — Addressed the "Home Manager base module" guard by unwrapping the collected override. `modules/home-manager/nixos.nix` now expands `flake.homeManagerModules.base.imports` directly (rather than handing the wrapper to Home Manager), which made `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'` advance to the next failure. The namespace stays intact all the way through System76; the current blocker is that Home Manager lacks option stubs for `home-manager.users.<owner>.apps` and related keys.
+- 2025-10-22 — Introduced `_user-bundles.nix` and rewired `modules/home-manager/nixos.nix` to feed bundle payloads into `users.<owner>.hmBundles.*`. The helper normalises import-tree wrappers, emits the base/gui/app/secret modules via `imports`, and is injected through `home-manager.sharedModules`. The scaffold now asserts `config.hmBundles.apps != { }`. Running `nix eval --accept-flake-config '.#nixosConfigurations.system76.config.home-manager.users.vx'` gets past the missing `flake.homeManagerModules.base` error and currently stops at a duplicate definition for `home-manager.users.vx.gui.i3.lockCommand`, signalling the next issue is conflicting GUI module merges.
+- 2025-10-22 — Deduplicated the GUI bundle by flattening `flake.homeManagerModules.gui.imports` in `modules/home-manager/nixos.nix` and reworking `_user-bundles.nix` to normalise module lists before injection. The duplicate i3 lockCommand error is gone; evaluation now fails because the upstream Home Manager module expects the legacy `home-manager.users.<owner>.apps` option. The new helper only defines `hmBundles.*`, so the next step is to supply a compatibility stub (or migrate the remaining writers) so those app definitions have an declared schema.
diff --git a/modules/hm-apps/claude-code.nix b/modules/hm-apps/claude-code.nix
index 6c336e208..8af6c6658 100644
--- a/modules/hm-apps/claude-code.nix
+++ b/modules/hm-apps/claude-code.nix
@@ -129,6 +129,7 @@
     in
     {
       config = {
+        programs.claude-code.enable = lib.mkDefault true;
         home.file.".claude/settings.json" = {
           text = builtins.toJSON claudeSettings;
           onChange = ''
diff --git a/modules/hm-apps/espanso.nix b/modules/hm-apps/espanso.nix
index 4ddaa3545..9c71ab171 100644
--- a/modules/hm-apps/espanso.nix
+++ b/modules/hm-apps/espanso.nix
@@ -40,19 +40,13 @@
 {
   flake.homeManagerModules.apps.espanso =
     { lib, pkgs, ... }:
-    let
-      inherit (pkgs.stdenv.hostPlatform) isLinux;
-    in
     {
-      services.espanso = {
-        enable = true;
-
-        # Enable both X11 and Wayland support on Linux for auto-detection
-        x11Support = lib.mkDefault isLinux;
-        waylandSupport = lib.mkDefault isLinux;
+      home.packages = [ pkgs.espanso ];
 
-        # Ensure Wayland package is available when waylandSupport is enabled
-        "package-wayland" = lib.mkDefault (if isLinux then pkgs.espanso-wayland else null);
+      services.espanso = {
+        enable = lib.mkForce true;
+        x11Support = lib.mkDefault true;
+        waylandSupport = lib.mkDefault false;
 
         # Default configuration
         configs = {
diff --git a/modules/hm-apps/starship.nix b/modules/hm-apps/starship.nix
new file mode 100644
index 000000000..652719b4f
--- /dev/null
+++ b/modules/hm-apps/starship.nix
@@ -0,0 +1,21 @@
+/*
+  Package: starship
+  Description: Cross-shell prompt with rich contextual information.
+  Homepage: https://starship.rs/
+  Documentation: https://starship.rs/config/
+  Repository: https://github.com/starship/starship
+
+  Summary:
+    * Provides fast, configurable shell prompts for Bash, Zsh, Fish, and more.
+    * Displays contextual data (Git status, language runtimes, time, battery) in a single line.
+
+  Example Usage:
+    * `starship preset nerd-font-symbols -o ~/.config/starship.toml` — Apply the Nerd Font preset.
+    * `starship explain` — Show how the prompt is rendered for debugging configurations.
+*/
+
+{
+  flake.homeManagerModules.apps.starship = _: {
+    programs.starship.enable = true;
+  };
+}
diff --git a/modules/home-manager/nixos.nix b/modules/home-manager/nixos.nix
index 4de3da5d8..e7246aaeb 100644
--- a/modules/home-manager/nixos.nix
+++ b/modules/home-manager/nixos.nix
@@ -46,19 +46,125 @@ builtins.trace "hm.nixos entry" {
               + (if combined != { } then lib.concatStringsSep ", " (lib.attrNames combined) else "<empty>")
             ) combined;
           configBase = lib.attrByPath [ "base" ] hmModules null;
-          baseModuleImports =
-            if configBase == null then
+          flattenImportTree =
+            value:
+            let
+              nestedImports = importsValue: if importsValue == null then [ ] else flattenImportTree importsValue;
+              contentImports = attrs: lib.attrByPath [ "imports" ] [ ] (lib.attrByPath [ "content" ] { } attrs);
+              shouldDescendImports =
+                attrs:
+                attrs ? imports
+                && !(attrs ? config)
+                && !(attrs ? options)
+                && !(attrs ? config')
+                && !(attrs ? _type && attrs._type == "override");
+            in
+            if value == null then
+              [ ]
+            else if lib.isList value then
+              lib.concatMap flattenImportTree value
+            else if lib.isAttrs value then
+              if value ? _type && value._type == "import-tree" then
+                nestedImports (contentImports value)
+              else if value ? _type && value._type == "order" then
+                nestedImports (contentImports value)
+              else if value ? _type && value ? content then
+                flattenImportTree value.content
+              else if shouldDescendImports value then
+                nestedImports value.imports
+              else
+                [ value ]
+            else
+              [ value ];
+          normalizeFileKey =
+            key:
+            if key == null then
+              null
+            else
+              let
+                parts = lib.splitString ", via option" key;
+              in
+              if parts == [ ] then key else lib.head parts;
+          moduleRawKey =
+            module:
+            if lib.isAttrs module && module ? _file then
+              module._file
+            else if lib.isAttrs module && module ? imports then
+              let
+                imports = module.imports or [ ];
+              in
+              if imports == [ ] then
+                null
+              else
+                let
+                  candidate = lib.head imports;
+                in
+                if lib.isAttrs candidate && candidate ? _file then
+                  candidate._file
+                else if builtins.isPath candidate then
+                  toString candidate
+                else if builtins.isString candidate then
+                  candidate
+                else
+                  null
+            else
+              null;
+          moduleKey = module: normalizeFileKey (moduleRawKey module);
+          baseModulePayload =
+            if lib.isAttrs configBase && lib.hasAttr "base" configBase then configBase.base else configBase;
+          baseModuleImportsRaw =
+            if lib.isAttrs baseModulePayload then lib.attrByPath [ "imports" ] [ ] baseModulePayload else [ ];
+          baseModulesRaw =
+            let
+              flattened = flattenImportTree baseModuleImportsRaw;
+              filtered =
+                let
+                  result = lib.filter (
+                    module:
+                    let
+                      rawKey = moduleRawKey module;
+                    in
+                    !(
+                      rawKey != null
+                      && (
+                        lib.hasInfix ", via option flake.homeManagerModules.apps." rawKey
+                        || lib.hasInfix ", via option flake.homeManagerModules.gui" rawKey
+                        || lib.hasInfix ", via option flake.homeManagerModules.context7Secrets" rawKey
+                        || lib.hasInfix ", via option flake.homeManagerModules.r2Secrets" rawKey
+                      )
+                    )
+                  ) flattened;
+                  message =
+                    "hm.nixos base modules: "
+                    + lib.concatStringsSep ", " (
+                      map (
+                        module:
+                        let
+                          key = moduleKey module;
+                        in
+                        if key != null then key else "<module>"
+                      ) result
+                    );
+                in
+                builtins.trace message result;
+            in
+            if filtered == [ ] then
               throw "Home Manager base module: expected flake.homeManagerModules.base to be available."
-            else if configBase ? imports then
-              configBase.imports
-            else if configBase ? content && configBase.content ? imports then
-              configBase.content.imports
             else
-              [ configBase ];
-          hmApps = hmModules.apps or { };
-          _hmAppsTrace = builtins.trace (
-            "hm.nixos hmApps: " + (if hmApps == null then "null" else builtins.typeOf hmApps)
-          ) null;
+              filtered;
+          moduleFromBase =
+            key:
+            if lib.isAttrs configBase && lib.hasAttr key configBase then
+              lib.getAttr key configBase
+            else
+              lib.attrByPath [ key ] hmModules null;
+          hmApps =
+            let
+              rawValue = moduleFromBase "apps";
+              result = if rawValue == null then { } else rawValue;
+              message = "hm.nixos hmApps: " + (if rawValue == null then "null" else builtins.typeOf result);
+            in
+            builtins.trace message result;
           hasApp = name: lib.hasAttr name hmApps;
           getApp =
             name:
@@ -74,15 +180,33 @@ builtins.trace "hm.nixos entry" {
             "ghq-mirror"
             "kitty"
             "alacritty"
+            "starship"
             "wezterm"
           ];
           extraAppImports = lib.attrByPath [ "home-manager" "extraAppImports" ] [ ] config;
           allAppImports = defaultAppImports ++ extraAppImports;
-          appModulesRaw = map getApp allAppImports;
-          guiModule = lib.attrByPath [ "gui" ] hmModules null;
-          context7SecretsModule = lib.attrByPath [ "context7Secrets" ] hmModules null;
-          r2SecretsModule = lib.attrByPath [ "r2Secrets" ] hmModules null;
-          importsList = [
+          appModules =
+            let
+              modules = lib.concatMap flattenImportTree (map getApp allAppImports);
+              message =
+                "hm.nixos app modules: "
+                + lib.concatStringsSep ", " (
+                  map (
+                    module:
+                    let
+                      key = moduleKey module;
+                    in
+                    if key != null then key else "<module>"
+                  ) modules
+                );
+            in
+            builtins.trace message modules;
+          guiModule = moduleFromBase "gui";
+          guiModules = flattenImportTree guiModule;
+          context7SecretsModules = flattenImportTree (moduleFromBase "context7Secrets");
+          r2SecretsModules = flattenImportTree (moduleFromBase "r2Secrets");
+          baseModules = baseModulesRaw;
+          baseImports = [
             inputs.sops-nix.homeManagerModules.sops
             (
               { osConfig, ... }:
@@ -90,14 +214,14 @@ builtins.trace "hm.nixos entry" {
                 home.stateVersion = osConfig.system.stateVersion;
               }
             )
-          ]
-          ++ baseModuleImports
-          ++ [
-            (if r2SecretsModule != null then r2SecretsModule else { })
-            (if context7SecretsModule != null then context7SecretsModule else { })
-          ]
-          ++ appModulesRaw;
-          appsForUsers = hmModules.apps or { };
+          ];
+          bundleImports = lib.concatLists [
+            baseModules
+            guiModules
+            appModules
+            context7SecretsModules
+            r2SecretsModules
+          ];
         in
         {
           useGlobalPkgs = true;
@@ -106,7 +230,8 @@ builtins.trace "hm.nixos entry" {
             inherit inputs;
           };
           backupFileExtension = "hm.bk";
-          users.${ownerName}.imports = importsList;
+          sharedModules = lib.mkBefore [ ];
+          users.${ownerName}.imports = baseImports ++ bundleImports;
         };
 
     };
diff --git a/modules/meta/flake-output.nix b/modules/meta/flake-output.nix
index a63b3c483..c4ffbcbe9 100644
--- a/modules/meta/flake-output.nix
+++ b/modules/meta/flake-output.nix
@@ -66,7 +66,9 @@
     };
   };
 
-  config.flake.lib = lib.mkDefault { };
-  config.flake.homeManagerModules = lib.mkDefault { };
-  config.flake.nixosModules = lib.mkDefault { };
+  config.flake = {
+    lib = lib.mkDefault { };
+    homeManagerModules = lib.mkDefault { };
+    nixosModules = lib.mkDefault { };
+  };
 }
diff --git a/modules/meta/nixos-helpers.nix b/modules/meta/nixos-helpers.nix
index b51c5a743..860e45b4e 100644
--- a/modules/meta/nixos-helpers.nix
+++ b/modules/meta/nixos-helpers.nix
@@ -1,5 +1,4 @@
-{ ... }:
-{
+_: {
   flake.nixosModules.base.imports = [
     ./flake-output.nix
     ./nixos-home-manager-collect.nix
diff --git a/modules/roles/pentesting-devshell.nix b/modules/roles/pentesting-devshell.nix
index 4588bef66..b831e20b4 100644
--- a/modules/roles/pentesting-devshell.nix
+++ b/modules/roles/pentesting-devshell.nix
@@ -21,10 +21,11 @@ let
   appModule = getAppModule appName;
 in
 {
-  flake.nixosModules.roles."pentesting-devshell" = _: {
-    config = {
-      home-manager.extraAppImports = lib.mkAfter [ appName ];
-      home-manager.sharedModules = lib.mkAfter [ appModule ];
+  flake.nixosModules.roles."pentesting-devshell" =
+    _:
+    builtins.seq appModule {
+      config = {
+        home-manager.extraAppImports = lib.mkAfter [ appName ];
+      };
     };
-  };
 }
diff --git a/modules/system76/home-manager-apps.nix b/modules/system76/home-manager-apps.nix
index ce51939ba..b0babfdf9 100644
--- a/modules/system76/home-manager-apps.nix
+++ b/modules/system76/home-manager-apps.nix
@@ -39,35 +39,9 @@ let
   ];
 in
 {
-  configurations.nixos.system76.module =
-    _:
-    let
-      appsDir = ../hm-apps;
-      getAppModule =
-        name:
-        let
-          filePath = appsDir + "/${name}.nix";
-        in
-        if builtins.pathExists filePath then
-          let
-            imported = import filePath;
-            module = lib.attrByPath [ "flake" "homeManagerModules" "apps" name ] null imported;
-          in
-          if module != null then
-            module
-          else
-            throw ("Home Manager app module '" + name + "' missing expected attrpath in " + toString filePath)
-        else
-          throw ("Home Manager app module file not found: " + toString filePath);
-      enableModuleFor =
-        name: if name == "claude-code" then { programs.claude-code.enable = lib.mkDefault true; } else null;
-      extraAppModules = map getAppModule extraAppNames;
-      extraEnableModules = lib.filter (m: m != null) (map enableModuleFor extraAppNames);
-    in
-    {
-      config = {
-        home-manager.extraAppImports = lib.mkAfter extraAppNames;
-        home-manager.sharedModules = lib.mkAfter (extraAppModules ++ extraEnableModules);
-      };
+  configurations.nixos.system76.module = _: {
+    config = {
+      home-manager.extraAppImports = lib.mkAfter extraAppNames;
     };
+  };
 }
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index 5fea5c123..f00c98a76 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -5,7 +5,7 @@
   ...
 }:
 let
-  flake = if config ? flake then config.flake else { };
+  flake = config.flake or { };
   selfFlake = config._module.args.self or inputs.self or null;
   moduleNamespace =
     attrs: name:
@@ -15,16 +15,15 @@ let
       nestedBase =
         lib.hasAttrByPath [ "content" "content" name ] attrs
         && lib.hasAttrByPath [ "content" name "imports" ] attrs.content;
-      _ = builtins.trace (
+      message =
         "system76 moduleNamespace "
         + name
         + ": "
         + (if direct then "direct " else "")
         + (if content then "content " else "")
-        + (if nestedBase then "nested " else "")
-      ) null;
+        + (if nestedBase then "nested " else "");
     in
-    direct || content || nestedBase;
+    builtins.trace message (direct || content || nestedBase);
   flakeNixosModulesBootstrap = import ./flake-nixosModules-bootstrap.nix;
   fallbackEval = lib.evalModules {
     modules = [
@@ -35,15 +34,21 @@ let
       (import ./../meta/nixos-app-helpers.nix)
     ];
     specialArgs = {
-      inherit lib inputs;
-      flake = flake;
+      inherit lib inputs flake;
       self = if selfFlake != null then selfFlake else { };
       system76NeedsFlakeBootstrap = true;
     };
   };
   fallbackNixosModules = fallbackEval.config.flake.nixosModules or { };
   fallbackHomeManagerModules = fallbackEval.config.flake.homeManagerModules or { };
-  nixosModulesFromConfig = flake.nixosModules or { };
+  nixosModulesFromConfig =
+    let
+      value = flake.nixosModules or { };
+      message =
+        "system76 nixos modules keys: "
+        + (if value != { } then builtins.concatStringsSep ", " (builtins.attrNames value) else "<empty>");
+    in
+    builtins.trace message value;
   nixosModulesFromSelf = if selfFlake != null then (selfFlake.nixosModules or { }) else { };
   nixosModules =
     if nixosModulesFromConfig != { } && moduleNamespace nixosModulesFromConfig "base" then
@@ -52,61 +57,32 @@ let
       nixosModulesFromSelf
     else
       fallbackNixosModules;
-  _nixosTrace = builtins.trace (
-    "system76 nixos modules keys: "
-    + (
-      if nixosModulesFromConfig != { } then
-        builtins.concatStringsSep ", " (builtins.attrNames nixosModulesFromConfig)
-      else
-        "<empty>"
-    )
-  ) null;
-  homeManagerModulesFromConfig = flake.homeManagerModules or { };
+  homeManagerModulesFromConfig =
+    let
+      value = flake.homeManagerModules or { };
+      keysMessage =
+        "system76 hmModulesFromConfig keys: "
+        + (if value == { } then "<empty>" else builtins.concatStringsSep ", " (builtins.attrNames value));
+      baseMessage =
+        "system76 hm config has base: "
+        + (if value != { } && moduleNamespace value "base" then "yes" else "no");
+    in
+    builtins.trace baseMessage (builtins.trace keysMessage value);
   homeManagerModulesFromSelf =
     if selfFlake != null then (selfFlake.homeManagerModules or { }) else { };
-  _hmConfigTypeTrace = builtins.trace (
-    "system76 hmModulesFromConfig keys: "
-    + (
-      if homeManagerModulesFromConfig == { } then
-        "<empty>"
-      else
-        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModulesFromConfig)
-    )
-  ) null;
-  _hmConfigTrace = builtins.trace (
-    "system76 hm config has base: "
-    + (
-      if homeManagerModulesFromConfig != { } && moduleNamespace homeManagerModulesFromConfig "base" then
-        "yes"
-      else
-        "no"
-    )
-  ) null;
+  mergedHomeManagerModules =
+    fallbackHomeManagerModules // homeManagerModulesFromSelf // homeManagerModulesFromConfig;
   homeManagerModules =
-    if homeManagerModulesFromConfig != { } && moduleNamespace homeManagerModulesFromConfig "base" then
-      homeManagerModulesFromConfig
-    else if homeManagerModulesFromSelf != { } && moduleNamespace homeManagerModulesFromSelf "base" then
-      homeManagerModulesFromSelf
-    else
-      fallbackHomeManagerModules;
-  _hmTrace = builtins.trace (
-    "system76 hm modules keys: "
-    + (
-      if homeManagerModules == { } then
-        "<empty>"
-      else
-        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
-    )
-  ) null;
-  _hmFinalTrace = builtins.trace (
-    "system76 hm keys before returning module: "
-    + (
-      if homeManagerModules == { } then
-        "<empty>"
-      else
-        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
-    )
-  ) null;
+    let
+      keys =
+        if mergedHomeManagerModules == { } then
+          "<empty>"
+        else
+          builtins.concatStringsSep ", " (builtins.attrNames mergedHomeManagerModules);
+      keysMessage = "system76 hm modules keys: " + keys;
+      finalMessage = "system76 hm keys before returning module: " + keys;
+    in
+    builtins.trace finalMessage (builtins.trace keysMessage mergedHomeManagerModules);
   hasModule = name: lib.hasAttr name nixosModules;
   getModule =
     name:
@@ -146,6 +122,13 @@ let
         "system76 host requires role " + name + " but it was not found in helpers or flake.nixosModules"
       );
   roleModules = map getRoleModule roleNames;
+  baseRoleModule = getRoleModule "base";
+  baseRoleAppModules =
+    let
+      imports = baseRoleModule.imports or [ ];
+      tail = if imports == [ ] then [ ] else lib.drop 1 imports;
+    in
+    lib.filter (module: module != null) tail;
   getVirtualizationModule =
     name:
     if lib.hasAttrByPath [ "virtualization" name ] nixosModules then
@@ -160,10 +143,11 @@ let
     "chat"
   ];
   workstationModule = getModule "workstation";
-  baseModule = getModule "base";
-  _baseTrace = builtins.trace (
-    "system76 baseModule present: " + (if baseModule == null then "no" else "yes")
-  ) null;
+  baseModule =
+    let
+      value = getModule "base";
+    in
+    builtins.trace ("system76 baseModule present: " + (if value == null then "no" else "yes")) value;
   flakeInitModule = _: {
     flake = lib.mkDefault { };
   };
@@ -172,22 +156,28 @@ let
     builtins.trace (
       "system76 baseModules includes " + name + ": " + (if module == null then "null" else "set")
     ) module;
+  bundleFlagModule =
+    {
+      lib,
+      ...
+    }:
+    {
+      _module.args.homeManagerBundleInjected = lib.mkDefault true;
+    };
   baseModulesRaw = [
     flakeNixosModulesBootstrap
     flakeInitModule
     (traceModule "base" baseModule)
+    bundleFlagModule
     (traceModule "inputs.hw.system76" inputs.nixos-hardware.nixosModules.system76)
     (traceModule "inputs.hw.system76-darp6" inputs.nixos-hardware.nixosModules.system76-darp6)
-    (traceModule "packages" (getModule "packages"))
     (traceModule "workstation" workstationModule)
     (traceModule "system76-support" (getModule "system76-support"))
-    (traceModule "security" (getModule "security"))
     (traceModule "hardware-lenovo-y27q-20" (getModule "hardware-lenovo-y27q-20"))
     (traceModule "duplicati-r2" (getModule "duplicati-r2"))
     (traceModule "virt" (getModule "virt"))
   ];
-  baseModules = lib.filter (module: module != null) baseModulesRaw;
-  _hmAfterBase = builtins.trace (
+  baseModules = builtins.trace (
     "system76 hm keys after baseModules: "
     + (
       if homeManagerModules == { } then
@@ -195,7 +185,7 @@ let
       else
         builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
     )
-  ) null;
+  ) (lib.filter (module: module != null) baseModulesRaw);
   virtualizationModules = lib.filter (module: module != null) (
     map
       (
@@ -229,21 +219,17 @@ let
 in
 {
   configurations.nixos.system76.module = {
-    _module.check = true;
-    _module.args.inputs = lib.mkDefault inputs;
-    _module.args.self = lib.mkDefault (inputs.self or null);
-    flake.homeManagerModules =
-      let
-        configHasBase =
-          homeManagerModulesFromConfig != { } && moduleNamespace homeManagerModulesFromConfig "base";
-      in
-      lib.mkIf (!configHasBase) (
-        lib.mkMerge [
-          fallbackHomeManagerModules
-        ]
-      );
+    _module = {
+      check = true;
+      args = {
+        inputs = lib.mkDefault inputs;
+        self = lib.mkDefault (inputs.self or null);
+      };
+    };
+    flake.homeManagerModules = mergedHomeManagerModules;
     imports =
       baseModules
+      ++ baseRoleAppModules
       ++ virtualizationModules
       ++ roleModules
       ++ lib.optional (hasModule "ssh") nixosModules.ssh;
@@ -272,6 +258,7 @@ in
         inherit inputs;
         self = inputs.self or null;
         system76NeedsFlakeBootstrap = true;
+        homeManagerBundleInjected = false;
       };
     };
   };
diff --git a/modules/system76/packages.nix b/modules/system76/packages.nix
index fe2a00fbf..6f1f29f90 100644
--- a/modules/system76/packages.nix
+++ b/modules/system76/packages.nix
@@ -16,6 +16,9 @@
       environment.systemPackages = lib.mkAfter (
         with pkgs;
         [
+          # Shell prompt
+          starship
+
           # System76 hardware utilities
           system76-power
           system76-scheduler
diff --git a/modules/workstation.nix b/modules/workstation.nix
index 9a70e4902..69aabb2d2 100644
--- a/modules/workstation.nix
+++ b/modules/workstation.nix
@@ -39,15 +39,6 @@ let
     else
       null;
 
-  resolveRole =
-    name:
-    let
-      result = resolveRoleOption name;
-    in
-    if result != null then
-      result
-    else
-      throw ("Unknown role '" + name + "' referenced by flake.nixosModules.workstation");
   appHelpers = config._module.args.nixosAppHelpers or { };
   rawAppHelpers = (config.flake.lib.nixos or { }) // appHelpers;
   fallbackGetApp =
@@ -114,16 +105,6 @@ let
       ];
     };
   };
-  baseImport =
-    if rawResolveRole "base" != null then
-      [ (resolveRole "base") ]
-    else if lib.hasAttrByPath [ "base" ] nixosModules then
-      [ (lib.getAttrFromPath [ "base" ] nixosModules) ]
-    else
-      throw "flake.nixosModules.base missing while constructing workstation bundle";
-  hmModules = flakeAttrs.homeManagerModules or { };
-  hmGuiModule = lib.attrByPath [ "gui" ] null hmModules;
-  hmAppModules = hmModules.apps or { };
   resolvedRoles = map (name: {
     inherit name;
     module = resolveRoleOption name;
@@ -135,7 +116,7 @@ let
 
   missingRoleNames = map (role: role.name) (lib.filter (role: role.module == null) resolvedRoles);
 
-  importsValue = baseImport ++ availableRoleModules ++ devLanguageModules;
+  importsValue = availableRoleModules ++ devLanguageModules;
 in
 {
   flake.nixosModules.workstation = {
@@ -147,26 +128,6 @@ in
           "workstation bundle requires roles that failed to resolve: "
           + lib.concatStringsSep ", " missingRoleNames
         );
-    config = lib.mkIf (hmGuiModule != null) (
-      let
-        extraNames = lib.attrByPath [ "home-manager" "extraAppImports" ] [ ] config;
-        getAppModule =
-          name:
-          let
-            module = lib.attrByPath [ name ] null hmAppModules;
-          in
-          if module != null then
-            module
-          else
-            throw ("Unknown Home Manager app '" + name + "' referenced by workstation role");
-        extraAppModules = map getAppModule extraNames;
-      in
-      {
-        # Append the GUI bundle for all Home Manager users while keeping the
-        # imports built by modules/home-manager/nixos.nix (which collect
-        # extraAppImports like flameshot).
-        home-manager.sharedModules = lib.mkAfter ([ hmGuiModule ] ++ extraAppModules);
-      }
-    );
+    config = { };
   };
 }

From 958523dfdd581265f5b43852344b5b3e03563c83 Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Thu, 23 Oct 2025 17:28:23 +0300
Subject: [PATCH 19/20] espanso only x11

---
 modules/hm-apps/espanso.nix | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/modules/hm-apps/espanso.nix b/modules/hm-apps/espanso.nix
index 9c71ab171..6e0a88ce7 100644
--- a/modules/hm-apps/espanso.nix
+++ b/modules/hm-apps/espanso.nix
@@ -8,7 +8,7 @@
   Summary:
     * Detects when you type a keyword (trigger) and replaces it with predefined text (expansion) while typing.
     * Supports variables (date, shell, clipboard), forms, regex triggers, and app-specific configurations.
-    * Works on X11 and Wayland (auto-detection based on $WAYLAND_DISPLAY).
+    * Configures the X11-native build to keep the setup lean on System76 desktops.
 
   Configuration:
     * Uses Home Manager's services.espanso module with declarative configs and matches.
@@ -17,12 +17,7 @@
     * Auto-generates YAML files to ~/.config/espanso/.
 
   Display Server Support:
-    * Both X11 and Wayland support enabled by default on Linux.
-    * Module sets x11Support=true, waylandSupport=true, and package-wayland=pkgs.espanso-wayland.
-    * Home Manager creates a wrapper that checks $WAYLAND_DISPLAY and launches the correct binary.
-    * To reduce closure size, disable unused support:
-      services.espanso.x11Support = false;  # Wayland-only
-      services.espanso.waylandSupport = false;  # X11-only
+    * Ships only the X11 build by default; enable Wayland manually if you need it.
 
   Example Usage:
     * Default setup provides common date/time variables and basic expansions.

From 8985bf11643cca5d9eba7001ff88641de953ea8e Mon Sep 17 00:00:00 2001
From: Bad3r <25513724+Bad3r@users.noreply.github.com>
Date: Mon, 27 Oct 2025 09:25:23 +0300
Subject: [PATCH 20/20] chore: to discard

---
 modules/home-manager/nixos.nix      | 75 ++++++++++------------
 modules/meta/nixos-role-helpers.nix | 32 +++-------
 modules/system76/imports.nix        | 96 +++++------------------------
 3 files changed, 57 insertions(+), 146 deletions(-)

diff --git a/modules/home-manager/nixos.nix b/modules/home-manager/nixos.nix
index e7246aaeb..1d19f8102 100644
--- a/modules/home-manager/nixos.nix
+++ b/modules/home-manager/nixos.nix
@@ -4,7 +4,7 @@
   lib,
   ...
 }:
-builtins.trace "hm.nixos entry" {
+{
   flake.nixosModules = {
     base = {
       imports = [ inputs.home-manager.nixosModules.home-manager ];
@@ -21,6 +21,33 @@ builtins.trace "hm.nixos entry" {
           ownerMeta = lib.attrByPath [ "lib" "meta" "owner" ] { } flakeAttrs;
           usersAttrs = config.users.users or { };
           normalUsers = lib.filterAttrs (_: u: (u.isNormalUser or false)) usersAttrs;
+          warnlessRenameModule =
+            { lib, ... }:
+            let
+              patchedLib = lib.extend (
+                _final: prev: {
+                  mkRenamedOptionModule =
+                    from: to:
+                    prev.doRename {
+                      inherit from to;
+                      visible = false;
+                      warn = false;
+                      use = prev.id;
+                    };
+                  mkRenamedOptionModuleWith =
+                    args:
+                    prev.doRename {
+                      inherit (args) from to;
+                      visible = false;
+                      warn = false;
+                      use = prev.id;
+                    };
+                }
+              );
+            in
+            {
+              _module.args.lib = patchedLib;
+            };
           ownerName =
             ownerMeta.username or (
               if normalUsers != { } then
@@ -41,10 +68,7 @@ builtins.trace "hm.nixos entry" {
                 );
                 if hmModulesFromConfig != { } then hmModulesFromConfig else hmModulesFromInputs;
             in
-            builtins.trace (
-              "hm.nixos hmModules keys: "
-              + (if combined != { } then lib.concatStringsSep ", " (lib.attrNames combined) else "<empty>")
-            ) combined;
+            combined;
           configBase = lib.attrByPath [ "base" ] hmModules null;
           flattenImportTree =
             value:
@@ -76,15 +100,6 @@ builtins.trace "hm.nixos entry" {
                 [ value ]
             else
               [ value ];
-          normalizeFileKey =
-            key:
-            if key == null then
-              null
-            else
-              let
-                parts = lib.splitString ", via option" key;
-              in
-              if parts == [ ] then key else lib.head parts;
           moduleRawKey =
             module:
             if lib.isAttrs module && module ? _file then
@@ -109,7 +124,6 @@ builtins.trace "hm.nixos entry" {
                   null
             else
               null;
-          moduleKey = module: normalizeFileKey (moduleRawKey module);
           baseModulePayload =
             if lib.isAttrs configBase && lib.hasAttr "base" configBase then configBase.base else configBase;
           baseModuleImportsRaw =
@@ -134,19 +148,8 @@ builtins.trace "hm.nixos entry" {
                       )
                     )
                   ) flattened;
-                  message =
-                    "hm.nixos base modules: "
-                    + lib.concatStringsSep ", " (
-                      map (
-                        module:
-                        let
-                          key = moduleKey module;
-                        in
-                        if key != null then key else "<module>"
-                      ) result
-                    );
                 in
-                builtins.trace message result;
+                result;
             in
             if filtered == [ ] then
               throw "Home Manager base module: expected flake.homeManagerModules.base to be available."
@@ -162,9 +165,8 @@ builtins.trace "hm.nixos entry" {
             let
               rawValue = moduleFromBase "apps";
               result = if rawValue == null then { } else rawValue;
-              message = "hm.nixos hmApps: " + (if rawValue == null then "null" else builtins.typeOf result);
             in
-            builtins.trace message result;
+            result;
           hasApp = name: lib.hasAttr name hmApps;
           getApp =
             name:
@@ -188,19 +190,8 @@ builtins.trace "hm.nixos entry" {
           appModules =
             let
               modules = lib.concatMap flattenImportTree (map getApp allAppImports);
-              message =
-                "hm.nixos app modules: "
-                + lib.concatStringsSep ", " (
-                  map (
-                    module:
-                    let
-                      key = moduleKey module;
-                    in
-                    if key != null then key else "<module>"
-                  ) modules
-                );
             in
-            builtins.trace message modules;
+            modules;
           guiModule = moduleFromBase "gui";
           guiModules = flattenImportTree guiModule;
           context7SecretsModules = flattenImportTree (moduleFromBase "context7Secrets");
@@ -230,7 +221,7 @@ builtins.trace "hm.nixos entry" {
             inherit inputs;
           };
           backupFileExtension = "hm.bk";
-          sharedModules = lib.mkBefore [ ];
+          sharedModules = lib.mkBefore [ warnlessRenameModule ];
           users.${ownerName}.imports = baseImports ++ bundleImports;
         };
 
diff --git a/modules/meta/nixos-role-helpers.nix b/modules/meta/nixos-role-helpers.nix
index 8f5ef777e..0f4ee2ea3 100644
--- a/modules/meta/nixos-role-helpers.nix
+++ b/modules/meta/nixos-role-helpers.nix
@@ -5,8 +5,6 @@
   ...
 }:
 let
-  enableTrace = builtins.getEnv "DEBUG_ROLES" == "1";
-  traceValue = msg: value: if enableTrace then builtins.trace msg value else value;
   sanitizeModule =
     module:
     if module == null then
@@ -22,13 +20,11 @@ let
               "imports"
             ];
           in
-          traceValue ("sanitizeModule has flake? " + (if module ? flake then "yes" else "no")) stripped;
+          stripped;
         imported = module.imports or [ ];
         sanitizedImports = lib.filter (m: m != null) (map sanitizeModule imported);
       in
-      traceValue (
-        "sanitizeModule direct keys: " + lib.concatStringsSep ", " (lib.attrNames cleaned)
-      ) cleaned
+      cleaned
       // lib.optionalAttrs (sanitizedImports != [ ]) {
         imports = sanitizedImports;
       }
@@ -53,21 +49,13 @@ let
         sanitizedDirect = lib.mapAttrs (
           name: value: if name == "flake" then value else sanitizeModule value
         ) direct;
-        tracedSanitizedDirect =
-          if sanitizedDirect ? flake then
-            traceValue (
-              "flattenRoles preserved flake keys: "
-              + lib.concatStringsSep ", " (lib.attrNames sanitizedDirect.flake)
-            ) sanitizedDirect
-          else
-            sanitizedDirect;
         imported = module.imports or [ ];
         merge = acc: value: acc // flattenRoles value;
-        merged = lib.foldl' merge tracedSanitizedDirect (
+        merged = lib.foldl' merge sanitizedDirect (
           if builtins.isList imported then imported else [ imported ]
         );
       in
-      traceValue ("flattenRoles merged keys: " + lib.concatStringsSep ", " (lib.attrNames merged)) merged
+      merged
     else
       { };
 
@@ -82,9 +70,7 @@ let
           let
             roles = flattenRoles config.flake.nixosModules.roles;
           in
-          traceValue (
-            "availableRoles.fromConfig keys: " + lib.concatStringsSep ", " (lib.attrNames roles)
-          ) roles
+          roles
         else
           { };
       fromSelf =
@@ -95,15 +81,11 @@ let
           let
             roles = flattenRoles (lib.getAttrFromPath [ "roles" ] selfModules);
           in
-          traceValue (
-            "availableRoles.fromSelf keys: " + lib.concatStringsSep ", " (lib.attrNames roles)
-          ) roles
+          roles
         else
           { };
     in
-    traceValue (
-      "availableRoles keys: " + lib.concatStringsSep ", " (lib.attrNames (fromConfig // fromSelf))
-    ) (fromConfig // fromSelf);
+    fromConfig // fromSelf;
 
   roleHelpers = rec {
     hasRole = name: builtins.hasAttr name availableRoles;
diff --git a/modules/system76/imports.nix b/modules/system76/imports.nix
index f00c98a76..f418f41bd 100644
--- a/modules/system76/imports.nix
+++ b/modules/system76/imports.nix
@@ -15,15 +15,8 @@ let
       nestedBase =
         lib.hasAttrByPath [ "content" "content" name ] attrs
         && lib.hasAttrByPath [ "content" name "imports" ] attrs.content;
-      message =
-        "system76 moduleNamespace "
-        + name
-        + ": "
-        + (if direct then "direct " else "")
-        + (if content then "content " else "")
-        + (if nestedBase then "nested " else "");
     in
-    builtins.trace message (direct || content || nestedBase);
+    direct || content || nestedBase;
   flakeNixosModulesBootstrap = import ./flake-nixosModules-bootstrap.nix;
   fallbackEval = lib.evalModules {
     modules = [
@@ -44,11 +37,8 @@ let
   nixosModulesFromConfig =
     let
       value = flake.nixosModules or { };
-      message =
-        "system76 nixos modules keys: "
-        + (if value != { } then builtins.concatStringsSep ", " (builtins.attrNames value) else "<empty>");
     in
-    builtins.trace message value;
+    value;
   nixosModulesFromSelf = if selfFlake != null then (selfFlake.nixosModules or { }) else { };
   nixosModules =
     if nixosModulesFromConfig != { } && moduleNamespace nixosModulesFromConfig "base" then
@@ -60,44 +50,14 @@ let
   homeManagerModulesFromConfig =
     let
       value = flake.homeManagerModules or { };
-      keysMessage =
-        "system76 hmModulesFromConfig keys: "
-        + (if value == { } then "<empty>" else builtins.concatStringsSep ", " (builtins.attrNames value));
-      baseMessage =
-        "system76 hm config has base: "
-        + (if value != { } && moduleNamespace value "base" then "yes" else "no");
     in
-    builtins.trace baseMessage (builtins.trace keysMessage value);
+    value;
   homeManagerModulesFromSelf =
     if selfFlake != null then (selfFlake.homeManagerModules or { }) else { };
   mergedHomeManagerModules =
     fallbackHomeManagerModules // homeManagerModulesFromSelf // homeManagerModulesFromConfig;
-  homeManagerModules =
-    let
-      keys =
-        if mergedHomeManagerModules == { } then
-          "<empty>"
-        else
-          builtins.concatStringsSep ", " (builtins.attrNames mergedHomeManagerModules);
-      keysMessage = "system76 hm modules keys: " + keys;
-      finalMessage = "system76 hm keys before returning module: " + keys;
-    in
-    builtins.trace finalMessage (builtins.trace keysMessage mergedHomeManagerModules);
   hasModule = name: lib.hasAttr name nixosModules;
-  getModule =
-    name:
-    let
-      hmKeys =
-        if homeManagerModules == { } then
-          "<empty>"
-        else
-          builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules);
-      messagePrefix = "system76 getModule(" + name + ") hm keys: " + hmKeys + " -> ";
-    in
-    if hasModule name then
-      builtins.trace (messagePrefix + "hit") (lib.getAttr name nixosModules)
-    else
-      builtins.trace (messagePrefix + "miss") null;
+  getModule = name: if hasModule name then lib.getAttr name nixosModules else null;
   roleHelpers =
     (config.flake.lib.nixos.roles or { }) // (config._module.args.nixosRoleHelpers or { });
   getRoleModule =
@@ -105,18 +65,11 @@ let
     let
       getRole = roleHelpers.getRole or (_: null);
       roleValue = getRole name;
-      hmKeys =
-        if homeManagerModules == { } then
-          "<empty>"
-        else
-          builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules);
     in
     if roleValue != null then
-      builtins.trace ("system76 getRoleModule(" + name + ") hm keys: " + hmKeys + " -> helper") roleValue
+      roleValue
     else if lib.hasAttrByPath [ "roles" name ] nixosModules then
-      builtins.trace ("system76 getRoleModule(" + name + ") hm keys: " + hmKeys + " -> flake") (
-        lib.getAttrFromPath [ "roles" name ] nixosModules
-      )
+      lib.getAttrFromPath [ "roles" name ] nixosModules
     else
       throw (
         "system76 host requires role " + name + " but it was not found in helpers or flake.nixosModules"
@@ -147,15 +100,10 @@ let
     let
       value = getModule "base";
     in
-    builtins.trace ("system76 baseModule present: " + (if value == null then "no" else "yes")) value;
+    value;
   flakeInitModule = _: {
     flake = lib.mkDefault { };
   };
-  traceModule =
-    name: module:
-    builtins.trace (
-      "system76 baseModules includes " + name + ": " + (if module == null then "null" else "set")
-    ) module;
   bundleFlagModule =
     {
       lib,
@@ -167,25 +115,17 @@ let
   baseModulesRaw = [
     flakeNixosModulesBootstrap
     flakeInitModule
-    (traceModule "base" baseModule)
+    baseModule
     bundleFlagModule
-    (traceModule "inputs.hw.system76" inputs.nixos-hardware.nixosModules.system76)
-    (traceModule "inputs.hw.system76-darp6" inputs.nixos-hardware.nixosModules.system76-darp6)
-    (traceModule "workstation" workstationModule)
-    (traceModule "system76-support" (getModule "system76-support"))
-    (traceModule "hardware-lenovo-y27q-20" (getModule "hardware-lenovo-y27q-20"))
-    (traceModule "duplicati-r2" (getModule "duplicati-r2"))
-    (traceModule "virt" (getModule "virt"))
+    inputs.nixos-hardware.nixosModules.system76
+    inputs.nixos-hardware.nixosModules.system76-darp6
+    workstationModule
+    (getModule "system76-support")
+    (getModule "hardware-lenovo-y27q-20")
+    (getModule "duplicati-r2")
+    (getModule "virt")
   ];
-  baseModules = builtins.trace (
-    "system76 hm keys after baseModules: "
-    + (
-      if homeManagerModules == { } then
-        "<empty>"
-      else
-        builtins.concatStringsSep ", " (builtins.attrNames homeManagerModules)
-    )
-  ) (lib.filter (module: module != null) baseModulesRaw);
+  baseModules = lib.filter (module: module != null) baseModulesRaw;
   virtualizationModules = lib.filter (module: module != null) (
     map
       (
@@ -193,9 +133,7 @@ let
         let
           module = getVirtualizationModule name;
         in
-        builtins.trace (
-          "system76 getVirtualizationModule(" + name + ") -> " + (if module == null then "null" else "set")
-        ) module
+        module
       )
       [
         "docker"