flake.nix

@@ -114,6 +114,7 @@
         baseModules = [
           ./lyrathorpe/user.nix
           ./system/modules/common-nixos.nix
+          ./system/modules/features.nix
           commonModule
           home-manager.nixosModules.home-manager
           {

lyrathorpe/swaywm.nix

@@ -11,9 +11,9 @@ let
   ctp = import ./catppuccin-mocha.nix;
 in
 {
-  options = {
-    features.swayDesktop.enable = lib.mkEnableOption "Enable Sway Desktop";
-  };
+  # The features.swayDesktop.enable option is declared in
+  # system/modules/features.nix (so headless hosts can read/set it without
+  # importing this module). This module only provides its implementation.
   config = lib.mkIf cfg.enable {
     programs.sway = {
       enable = true;

system/modules/features.nix

@@ -0,0 +1,12 @@
+# Feature-flag option declarations shared by every NixOS host (imported via
+# baseModules in flake.nix). Declaring the flags here -- rather than inside the
+# module that implements them -- means a host can read or set a flag without
+# importing the (often large) implementation module. In particular,
+# features.swayDesktop.enable is read by lyrathorpe/user.nix on every host, but a
+# headless host (e.g. the Pi) must be able to leave it at its default without
+# pulling in lyrathorpe/swaywm.nix. The implementation lives in swaywm.nix,
+# gated on this flag.
+{ lib, ... }:
+{
+  options.features.swayDesktop.enable = lib.mkEnableOption "the Sway desktop";
+}