From 3d0c281fd6ca079e161f3c226e5f8cc1a3e7e49a Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Mon, 20 Oct 2025 18:24:10 +0200
Subject: [PATCH 1/2] inventory: add clanLib to specialArgs

---
 .../all-services-wrapper.nix                  |  8 ++--
 .../distributed-service/tests/default.nix     |  1 +
 .../distributed-service/tests/specialArgs.nix | 40 +++++++++++++++++++
 3 files changed, 46 insertions(+), 3 deletions(-)
 create mode 100644 lib/modules/inventory/distributed-service/tests/specialArgs.nix

diff --git a/lib/modules/inventory/distributed-service/all-services-wrapper.nix b/lib/modules/inventory/distributed-service/all-services-wrapper.nix
index eda9940ab..d250ed517 100644
--- a/lib/modules/inventory/distributed-service/all-services-wrapper.nix
+++ b/lib/modules/inventory/distributed-service/all-services-wrapper.nix
@@ -27,14 +27,16 @@ in
         placeholder = "mappedServiceName";
         elemType = submoduleWith {
           class = "clan.service";
+          specialArgs = {
+            exports = config.exports;
+            directory = directory;
+            clanLib = specialArgs.clanLib;
+          };
           modules = [
             (
               { name, ... }:
               {
                 _module.args._ctx = [ name ];
-                _module.args.exports = config.exports;
-                _module.args.directory = directory;
-
               }
             )
             ./service-module.nix
diff --git a/lib/modules/inventory/distributed-service/tests/default.nix b/lib/modules/inventory/distributed-service/tests/default.nix
index a58d8390e..6a7beb4db 100644
--- a/lib/modules/inventory/distributed-service/tests/default.nix
+++ b/lib/modules/inventory/distributed-service/tests/default.nix
@@ -56,6 +56,7 @@ in
   extraModules = import ./extraModules.nix { inherit clanLib; };
   exports = import ./exports.nix { inherit lib clanLib; };
   settings = import ./settings.nix { inherit lib callInventoryAdapter; };
+  specialArgs = import ./specialArgs.nix { inherit lib callInventoryAdapter; };
   resolve_module_spec = import ./import_module_spec.nix { inherit lib callInventoryAdapter; };
   test_simple =
     let
diff --git a/lib/modules/inventory/distributed-service/tests/specialArgs.nix b/lib/modules/inventory/distributed-service/tests/specialArgs.nix
new file mode 100644
index 000000000..8670f0e45
--- /dev/null
+++ b/lib/modules/inventory/distributed-service/tests/specialArgs.nix
@@ -0,0 +1,40 @@
+{ callInventoryAdapter, lib, ... }:
+let
+  res = callInventoryAdapter {
+    modules."A" = m: {
+      _class = "clan.service";
+      config = {
+        manifest = {
+          name = "network";
+        };
+        roles.default = { };
+
+      };
+      options.test = lib.mkOption {
+        default = m;
+      };
+    };
+    machines = {
+      jon = { };
+    };
+    instances."instance_foo" = {
+      module = {
+        name = "A";
+        input = "self";
+      };
+      roles.peer.machines.jon = { };
+    };
+  };
+
+  specialArgs = lib.attrNames res.servicesEval.config.mappedServices.self-A.test.specialArgs;
+in
+{
+  test_simple = {
+    expr = specialArgs;
+    expected = [
+      "clanLib"
+      "directory"
+      "exports"
+    ];
+  };
+}

From 3ffad3f97f8e95068b07564f48cffe51cf247e64 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Mon, 20 Oct 2025 18:24:37 +0200
Subject: [PATCH 2/2] inventory: add docs for available specialArgs in service
 submodules

---
 lib/modules/inventory/flake-module.nix | 29 +++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/lib/modules/inventory/flake-module.nix b/lib/modules/inventory/flake-module.nix
index fe4727e2b..4cbea8dd5 100644
--- a/lib/modules/inventory/flake-module.nix
+++ b/lib/modules/inventory/flake-module.nix
@@ -38,7 +38,34 @@
         (pkgs.nixosOptionsDoc {
           options =
             (self.clanLib.evalService {
-              modules = [ { _docs_rendering = true; } ];
+              modules = [
+                { _docs_rendering = true; }
+                {
+                  options."#specialArgs" = lib.mkOption {
+                    description = ''
+                      Adidtional arguments passed to the module. Often referred to as `specialArgs`.
+
+                      ```nix
+                      {
+                        # root directory of the clan
+                        directory,
+                        # clanLib - The clan library functions
+                        clanLib,
+                        # exports from all services
+                        exports,
+                        ...
+                      }:
+                      {
+                        _class = "clan.service";
+                        manifest.name = "example-service";
+
+                        # ... elided
+                      }
+                      ```
+                    '';
+                  };
+                }
+              ];
               prefix = [ ];
             }).options;
           warningsAreErrors = true;