Update nixpkgs

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5723

checks/flash/flake-module.nix

@@ -58,20 +58,22 @@
         pkgs.buildPackages.xorg.lndir
         pkgs.glibcLocales
         pkgs.kbd.out
-        self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".pkgs.perlPackages.ConfigIniFiles
-        self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".pkgs.perlPackages.FileSlurp
+        self.nixosConfigurations."test-flash-machine-${pkgs.stdenv.hostPlatform.system}".pkgs.perlPackages.ConfigIniFiles
+        self.nixosConfigurations."test-flash-machine-${pkgs.stdenv.hostPlatform.system}".pkgs.perlPackages.FileSlurp
         pkgs.bubblewrap
 
-        self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".config.system.build.toplevel
-        self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".config.system.build.diskoScript
-        self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".config.system.build.diskoScript.drvPath
+        self.nixosConfigurations."test-flash-machine-${pkgs.stdenv.hostPlatform.system}".config.system.build.toplevel
+        self.nixosConfigurations."test-flash-machine-${pkgs.stdenv.hostPlatform.system}".config.system.build.diskoScript
+        self.nixosConfigurations."test-flash-machine-${pkgs.stdenv.hostPlatform.system}".config.system.build.diskoScript.drvPath
       ]
       ++ builtins.map (i: i.outPath) (builtins.attrValues self.inputs);
       closureInfo = pkgs.closureInfo { rootPaths = dependencies; };
     in
     {
       # Skip flash test on aarch64-linux for now as it's too slow
-      checks = lib.optionalAttrs (pkgs.stdenv.isLinux && pkgs.hostPlatform.system != "aarch64-linux") {
+      checks =
+        lib.optionalAttrs (pkgs.stdenv.isLinux && pkgs.stdenv.hostPlatform.system != "aarch64-linux")
+          {
             nixos-test-flash = self.clanLib.test.baseTest {
               name = "flash";
               nodes.target = {
@@ -100,7 +102,7 @@
                 machine.succeed("echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIRWUusawhlIorx7VFeQJHmMkhl9X3QpnvOdhnV/bQNG root@target' > ./test_id_ed25519.pub")
                 # Some distros like to automount disks with spaces
                 machine.succeed('mkdir -p "/mnt/with spaces" && mkfs.ext4 /dev/vdc && mount /dev/vdc "/mnt/with spaces"')
-            machine.succeed("clan flash write --ssh-pubkey ./test_id_ed25519.pub --keymap de --language de_DE.UTF-8 --debug --flake ${self.checks.x86_64-linux.clan-core-for-checks} --yes --disk main /dev/vdc test-flash-machine-${pkgs.hostPlatform.system}")
+                machine.succeed("clan flash write --ssh-pubkey ./test_id_ed25519.pub --keymap de --language de_DE.UTF-8 --debug --flake ${self.checks.x86_64-linux.clan-core-for-checks} --yes --disk main /dev/vdc test-flash-machine-${pkgs.stdenv.hostPlatform.system}")
               '';
             } { inherit pkgs self; };
           };

checks/installation/flake-module.nix

@@ -160,9 +160,9 @@
           closureInfo = pkgs.closureInfo {
             rootPaths = [
               privateInputs.clan-core-for-checks
-              self.nixosConfigurations."test-install-machine-${pkgs.hostPlatform.system}".config.system.build.toplevel
-              self.nixosConfigurations."test-install-machine-${pkgs.hostPlatform.system}".config.system.build.initialRamdisk
-              self.nixosConfigurations."test-install-machine-${pkgs.hostPlatform.system}".config.system.build.diskoScript
+              self.nixosConfigurations."test-install-machine-${pkgs.stdenv.hostPlatform.system}".config.system.build.toplevel
+              self.nixosConfigurations."test-install-machine-${pkgs.stdenv.hostPlatform.system}".config.system.build.initialRamdisk
+              self.nixosConfigurations."test-install-machine-${pkgs.stdenv.hostPlatform.system}".config.system.build.diskoScript
               pkgs.stdenv.drvPath
               pkgs.bash.drvPath
               pkgs.buildPackages.xorg.lndir
@@ -215,7 +215,7 @@
                   # Prepare test flake and Nix store
                   flake_dir = prepare_test_flake(
                       temp_dir,
-                      "${self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks}",
+                      "${self.checks.${pkgs.stdenv.hostPlatform.system}.clan-core-for-checks}",
                       "${closureInfo}"
                   )
 
@@ -296,7 +296,7 @@
                   # Prepare test flake and Nix store
                   flake_dir = prepare_test_flake(
                       temp_dir,
-                      "${self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks}",
+                      "${self.checks.${pkgs.stdenv.hostPlatform.system}.clan-core-for-checks}",
                       "${closureInfo}"
                   )
 

checks/llm/default.nix

@@ -2,7 +2,7 @@
 
 let
 
-  cli = self.packages.${pkgs.hostPlatform.system}.clan-cli-full;
+  cli = self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli-full;
 
   ollama-model = pkgs.callPackage ./qwen3-4b-instruct.nix { };
 in
@@ -53,7 +53,7 @@ in
               pytest
               pytest-xdist
               (cli.pythonRuntime.pkgs.toPythonModule cli)
-              self.legacyPackages.${pkgs.hostPlatform.system}.nixosTestLib
+              self.legacyPackages.${pkgs.stdenv.hostPlatform.system}.nixosTestLib
             ]
           ))
         ];

checks/systemd-abstraction/default.nix

@@ -2,7 +2,7 @@
 
 let
 
-  cli = self.packages.${pkgs.hostPlatform.system}.clan-cli-full;
+  cli = self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli-full;
 in
 {
   name = "systemd-abstraction";

checks/update/flake-module.nix

@@ -115,9 +115,9 @@
               let
                 closureInfo = pkgs.closureInfo {
                   rootPaths = [
-                    self.packages.${pkgs.hostPlatform.system}.clan-cli
-                    self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks
-                    self.clanInternals.machines.${pkgs.hostPlatform.system}.test-update-machine.config.system.build.toplevel
+                    self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli
+                    self.checks.${pkgs.stdenv.hostPlatform.system}.clan-core-for-checks
+                    self.clanInternals.machines.${pkgs.stdenv.hostPlatform.system}.test-update-machine.config.system.build.toplevel
                     pkgs.stdenv.drvPath
                     pkgs.bash.drvPath
                     pkgs.buildPackages.xorg.lndir
@@ -132,7 +132,7 @@
                   imports = [ self.nixosModules.test-update-machine ];
                 };
                 extraPythonPackages = _p: [
-                  self.legacyPackages.${pkgs.hostPlatform.system}.nixosTestLib
+                  self.legacyPackages.${pkgs.stdenv.hostPlatform.system}.nixosTestLib
                 ];
 
                 testScript = ''
@@ -154,7 +154,7 @@
                       # Prepare test flake and Nix store
                       flake_dir = prepare_test_flake(
                           temp_dir,
-                          "${self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks}",
+                          "${self.checks.${pkgs.stdenv.hostPlatform.system}.clan-core-for-checks}",
                           "${closureInfo}"
                       )
                       (flake_dir / ".clan-flake").write_text("")  # Ensure .clan-flake exists
@@ -226,7 +226,7 @@
                             "--to",
                             "ssh://root@192.168.1.1",
                             "--no-check-sigs",
-                            f"${self.packages.${pkgs.hostPlatform.system}.clan-cli}",
+                            f"${self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli}",
                             "--extra-experimental-features", "nix-command flakes",
                         ],
                         check=True,
@@ -242,7 +242,7 @@
                           "-o", "UserKnownHostsFile=/dev/null",
                           "-o", "StrictHostKeyChecking=no",
                           f"root@192.168.1.1",
-                          "${self.packages.${pkgs.hostPlatform.system}.clan-cli}/bin/clan",
+                          "${self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli}/bin/clan",
                           "machines",
                           "update",
                           "--debug",
@@ -270,7 +270,7 @@
 
                       # Run clan update command
                       subprocess.run([
-                          "${self.packages.${pkgs.hostPlatform.system}.clan-cli-full}/bin/clan",
+                          "${self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli-full}/bin/clan",
                           "machines",
                           "update",
                           "--debug",
@@ -297,7 +297,7 @@
 
                       # Run clan update command with --build-host
                       subprocess.run([
-                          "${self.packages.${pkgs.hostPlatform.system}.clan-cli-full}/bin/clan",
+                          "${self.packages.${pkgs.stdenv.hostPlatform.system}.clan-cli-full}/bin/clan",
                           "machines",
                           "update",
                           "--debug",

clanServices/certificates/README.md

@@ -1,3 +1,6 @@
+!!! Danger "Experimental"
+    This service is experimental and will change in the future.
+
 This service sets up a certificate authority (CA) that can issue certificates to
 other machines in your clan. For this the `ca` role is used.
 It additionally provides a `default` role, that can be applied to all machines

clanServices/coredns/README.md

@@ -1,3 +1,6 @@
+!!! Danger "Experimental"
+    This service is experimental and will change in the future.
+
 This module enables hosting clan-internal services easily, which can be resolved
 inside your VPN. This allows defining a custom top-level domain (e.g. `.clan`)
 and exposing endpoints from a machine to others, which will be

clanServices/hello-world/README.md

@@ -1 +1,83 @@
-This a test README just to appease the eval warnings if we don't have one
+!!! Danger "Experimental"
+    This service is for demonstration purpose only and may change in the future.
+
+The Hello-World Clan Service is a minimal example showing how to build and register your own service.
+
+It serves as a reference implementation and is used in clan-core CI tests to ensure compatibility.
+
+## What it demonstrates
+
+- How to define a basic Clan-compatible service.
+- How to structure your service for discovery and configuration.
+- How Clan services interact with nixos.
+
+## Testing
+
+This service demonstrates two levels of testing to ensure quality and stability across releases:
+
+1. **Unit & Integration Testing** — via [`nix-unit`](https://github.com/nix-community/nix-unit)
+2. **End-to-End Testing** — via **NixOS VM tests**, which we extended to support **container virtualization** for better performance.
+
+We highly advocate following the [Practical Testing Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html):
+
+* Write **unit tests** for core logic and invariants.
+* Add **one or two end-to-end (E2E)** tests to confirm your service starts and behaves correctly in a real NixOS environment.
+
+NixOS is **untyped** and frequently changes; tests are the safest way to ensure long-term stability of services.
+
+```
+               / \
+              /   \
+             / E2E \
+            /-------\
+           /         \
+          /Integration\
+         /-------------\
+        /               \
+       /    Unit Tests   \
+       -------------------
+```
+
+### nix-unit
+
+We highly advocate the usage of
+
+[nix-unit](https://github.com/nix-community/nix-unit)
+
+Example in: tests/eval-tests.nix
+
+If you use flake-parts you can use the [native integration](https://flake.parts/options/nix-unit.html)
+
+If nix-unit succeeds you'r nixos evaluation should be mostly correct.
+
+!!! Tip
+    - Ensure most used 'settings' and variants are tested.
+    - Think about some important edge-cases your system should handle.
+
+### NixOS VM / Container Test
+
+!!! Warning "Early Vars & clanTest"
+    The testing system around vars is experimental
+
+    `clanTest` is still experimental and enables container virtualization by default.
+    This is still early and might have some limitations.
+
+Some minimal boilerplate is needed to use `clanTest`
+
+```nix
+nixosLib = import (inputs.nixpkgs + "/nixos/lib") { }
+nixosLib.runTest (
+    { ... }:
+    {
+        imports = [
+            self.modules.nixosTest.clanTest
+            # Example in tests/vm/default.nix
+            testModule
+        ];
+        hostPkgs = pkgs;
+
+        # Uncomment if you don't want or cannot use containers
+        # test.useContainers = false;
+    }
+)
+```

clanServices/hello-world/default.nix

@@ -8,7 +8,7 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/hello-word";
-  manifest.description = "This is a test";
+  manifest.description = "Minimal example clan service that greets the world";
   manifest.readme = builtins.readFile ./README.md;
 
   # This service provides two roles: "morning" and "evening". Roles can be

clanServices/hello-world/flake-module.nix

@@ -26,7 +26,7 @@ in
             # The hello-world service being tested
             ../../clanServices/hello-world
             # Required modules
-            ../../nixosModules/clanCore
+            ../../nixosModules
           ];
           testName = "hello-world";
           tests = ./tests/eval-tests.nix;

clanServices/hello-world/tests/eval-tests.nix

@@ -4,7 +4,7 @@
   ...
 }:
 let
-  testFlake = clanLib.clan {
+  testClan = clanLib.clan {
     self = { };
     # Point to the folder of the module
     # TODO: make this optional
@@ -33,10 +33,20 @@ let
   };
 in
 {
-  test_simple = {
-    config = testFlake.config;
+  /**
+    We highly advocate the usage of:
+    https://github.com/nix-community/nix-unit
 
-    expr = { };
-    expected = { };
+    If you use flake-parts you can use the native integration: https://flake.parts/options/nix-unit.html
+  */
+  test_simple = {
+    # Allows inspection via the nix-repl
+    # Ignored by nix-unit; it only looks at 'expr' and 'expected'
+    inherit testClan;
+
+    # Assert that jon has the
+    # configured greeting in 'environment.etc.hello.text'
+    expr = testClan.config.nixosConfigurations.jon.config.environment.etc."hello".text;
+    expected = "Good evening World!";
   };
 }

clanServices/internet/README.md

@@ -1,8 +1,5 @@
-🚧🚧🚧 Experimental 🚧🚧🚧
-
-Use at your own risk.
-
-We are still refining its interfaces, instability and breakages are expected.
+!!! Danger "Experimental"
+    This service is experimental and will change in the future.
 
 ---
 

clanServices/monitoring/README.md

@@ -1,3 +1,6 @@
+!!! Danger "Experimental"
+    This service is experimental and will change in the future.
+
 ## Usage
 
 ```

clanServices/syncthing/flake-module.nix

@@ -22,6 +22,7 @@ in
             ../../clanServices/syncthing
             # Required modules
             ../../nixosModules/clanCore
+            ../../nixosModules/machineModules
             # Dependencies like clan-cli
             ../../pkgs/clan-cli
           ];

clanServices/tor/README.md

@@ -1,8 +1,5 @@
-🚧🚧🚧 Experimental 🚧🚧🚧
-
-Use at your own risk.
-
-We are still refining its interfaces, instability and breakages are expected.
+!!! Danger "Experimental"
+    This service is experimental and will change in the future.
 
 ---
 

clanServices/wifi/tests/eval-tests.nix

@@ -41,14 +41,14 @@ let
   # In this case it is 'self-zerotier-redux'
   # This is usually only used internally, but we can use it to test the evaluation of service module in isolation
   # evaluatedService =
-  #   testFlake.clanInternals.inventoryClass.distributedServices.importedModulesEvaluated.self-zerotier-redux.config;
+  #   testFlake.clanInternals.inventoryClass.distributedServices.servicesEval.config.mappedServices.self-zerotier-redux.config;
 in
 {
   test_simple = {
     inherit testFlake;
 
     expr =
-      testFlake.config.clan.clanInternals.inventoryClass.distributedServices.importedModulesEvaluated.self-wifi.config;
+      testFlake.config.clan.clanInternals.inventoryClass.distributedServices.servicesEval.config.mappedServices.self-wifi.config;
     expected = 1;
 
     # expr = {

clanServices/yggdrasil/README.md

@@ -1,8 +1,5 @@
-🚧🚧🚧 Experimental 🚧🚧🚧
-
-Use at your own risk.
-
-We are still refining its interfaces, instability and breakages are expected.
+!!! Danger "Experimental"
+    This service is experimental and will change in the future.
 
 ---
 

clanServices/zerotier/flake-module.nix

@@ -21,6 +21,7 @@ in
             ../../clanServices/zerotier
             # Required modules
             ../../nixosModules/clanCore
+            ../../nixosModules/machineModules
             # Dependencies like clan-cli
             ../../pkgs/clan-cli
           ];

devFlake/flake.lock

@@ -105,11 +105,11 @@
     },
     "nixpkgs-dev": {
       "locked": {
-        "lastModified": 1761458099,
-        "narHash": "sha256-XeAdn1NidGKXSwlepyjH+n58hsCDqbpx1M8sdDM2Ggc=",
+        "lastModified": 1762080734,
+        "narHash": "sha256-fFunzA7ITlPHRr7dECaFGTBucNiWYEVDNPBw/9gFmII=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "d8cc1036c65d3c9468a91443a75b51276279ac61",
+        "rev": "bc7f6fa86de9b208edf4ea7bbf40bcd8cc7d70a5",
         "type": "github"
       },
       "original": {
@@ -128,11 +128,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1760652422,
-        "narHash": "sha256-C88Pgz38QIl9JxQceexqL2G7sw9vodHWx1Uaq+NRJrw=",
+        "lastModified": 1761730856,
+        "narHash": "sha256-t1i5p/vSWwueZSC0Z2BImxx3BjoUDNKyC2mk24krcMY=",
         "owner": "NuschtOS",
         "repo": "search",
-        "rev": "3ebeebe8b6a49dfb11f771f761e0310f7c48d726",
+        "rev": "e29de6db0cb3182e9aee75a3b1fd1919d995d85b",
         "type": "github"
       },
       "original": {

docs/site/getting-started/creating-your-first-clan.md

@@ -51,7 +51,7 @@ Make sure you have the following:
     **Note:** This creates a new directory in your current location
 
     ```shellSession
-    nix run https://git.clan.lol/clan/clan-core/archive/main.tar.gz#clan-cli --refresh -- flakes create
+    nix run "https://git.clan.lol/clan/clan-core/archive/main.tar.gz#clan-cli" --refresh -- flakes create
     ```
 
 3. Enter a **name** in the prompt:

flake.lock

@@ -31,11 +31,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1760701190,
-        "narHash": "sha256-y7UhnWlER8r776JsySqsbTUh2Txf7K30smfHlqdaIQw=",
+        "lastModified": 1761899396,
+        "narHash": "sha256-XOpKBp6HLzzMCbzW50TEuXN35zN5WGQREC7n34DcNMM=",
         "owner": "nix-community",
         "repo": "disko",
-        "rev": "3a9450b26e69dcb6f8de6e2b07b3fc1c288d85f5",
+        "rev": "6f4cf5abbe318e4cd1e879506f6eeafd83f7b998",
         "type": "github"
       },
       "original": {
@@ -51,11 +51,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1760948891,
-        "narHash": "sha256-TmWcdiUUaWk8J4lpjzu4gCGxWY6/Ok7mOK4fIFfBuU4=",
+        "lastModified": 1762040540,
+        "narHash": "sha256-z5PlZ47j50VNF3R+IMS9LmzI5fYRGY/Z5O5tol1c9I4=",
         "owner": "hercules-ci",
         "repo": "flake-parts",
-        "rev": "864599284fc7c0ba6357ed89ed5e2cd5040f0c04",
+        "rev": "0010412d62a25d959151790968765a70c436598b",
         "type": "github"
       },
       "original": {
@@ -71,11 +71,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1760721282,
-        "narHash": "sha256-aAHphQbU9t/b2RRy2Eb8oMv+I08isXv2KUGFAFn7nCo=",
+        "lastModified": 1762039661,
+        "narHash": "sha256-oM5BwAGE78IBLZn+AqxwH/saqwq3e926rNq5HmOulkc=",
         "owner": "nix-darwin",
         "repo": "nix-darwin",
-        "rev": "c3211fcd0c56c11ff110d346d4487b18f7365168",
+        "rev": "c3c8c9f2a5ed43175ac4dc030308756620e6e4e4",
         "type": "github"
       },
       "original": {
@@ -115,10 +115,10 @@
     "nixpkgs": {
       "locked": {
         "lastModified": 315532800,
-        "narHash": "sha256-yDxtm0PESdgNetiJN5+MFxgubBcLDTiuSjjrJiyvsvM=",
-        "rev": "d7f52a7a640bc54c7bb414cca603835bf8dd4b10",
+        "narHash": "sha256-LDT9wuUZtjPfmviCcVWif5+7j4kBI2mWaZwjNNeg4eg=",
+        "rev": "a7fc11be66bdfb5cdde611ee5ce381c183da8386",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre871443.d7f52a7a640b/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre887438.a7fc11be66bd/nixexprs.tar.xz"
       },
       "original": {
         "type": "tarball",

flakeModules/clan.nix

@@ -39,32 +39,10 @@ in
           };
           modules = [
             clan-core.modules.clan.default
-            {
-              checks.minNixpkgsVersion = {
-                assertion = lib.versionAtLeast nixpkgs.lib.version "25.11";
-                message = ''
-                  Nixpkgs version: ${nixpkgs.lib.version} is incompatible with clan-core. (>= 25.11 is recommended)
-                  ---
-                  Your version of 'nixpkgs' seems too old for clan-core.
-                  Please read: https://docs.clan.lol/guides/nixpkgs-flake-input
-
-                  You can ignore this check by setting:
-                  clan.checks.minNixpkgsVersion.ignore = true;
-                  ---
-                '';
-              };
-            }
           ];
         };
-        apply =
-          config:
-          lib.deepSeq (lib.mapAttrs (
-            id: check:
-            if check.ignore || check.assertion then
-              null
-            else
-              throw "clan.checks.${id} failed with message\n${check.message}"
-          ) config.checks) config;
+        # Important: !This logic needs to be kept in sync with lib.clan function!
+        apply = config: clan-core.lib.checkConfig config.checks config;
       };
 
     # Mapped flake toplevel outputs

lib/clan/checkConfig.nix

@@ -0,0 +1,19 @@
+{ lib, ... }:
+/**
+  Function to assert clan configuration checks.
+
+  Arguments:
+
+  - 'checks' attribute of clan configuration
+  - Any: the returned configuration (can be anything, is just passed through)
+*/
+checks:
+lib.deepSeq (
+  lib.mapAttrs (
+    id: check:
+    if check.ignore || check.assertion then
+      null
+    else
+      throw "clan.checks.${id} failed with message\n${check.message}"
+  ) checks
+)

lib/clan/default.nix

@@ -33,8 +33,8 @@
 let
   nixpkgs = self.inputs.nixpkgs or clan-core.inputs.nixpkgs;
   nix-darwin = self.inputs.nix-darwin or clan-core.inputs.nix-darwin;
-in
-lib.evalModules {
+  configuration = (
+    lib.evalModules {
       class = "clan";
       specialArgs = {
         inherit
@@ -49,4 +49,7 @@ lib.evalModules {
         clan-core.modules.clan.default
         m
       ];
-}
+    }
+  );
+in
+clan-core.clanLib.checkConfig configuration.config.checks configuration

lib/default.nix

@@ -16,6 +16,8 @@ lib.fix (
       */
       callLib = file: args: import file ({ inherit lib clanLib; } // args);
 
+      checkConfig = clanLib.callLib ./clan/checkConfig.nix { };
+
       evalService = clanLib.callLib ./evalService.nix { };
       # ------------------------------------
       # ClanLib functions

lib/dir_test.nix

@@ -53,7 +53,12 @@ in
             };
           };
         }).clan
-          { config.directory = rootPath; };
+          {
+            directory = rootPath;
+            self = {
+              inputs.nixpkgs.lib.version = "25.11";
+            };
+          };
     in
     {
       inherit vclan;
@@ -94,7 +99,12 @@ in
             };
           };
         }).clan
-          { config.directory = rootPath; };
+          {
+            directory = rootPath;
+            self = {
+              inputs.nixpkgs.lib.version = "25.11";
+            };
+          };
     in
     {
       inherit vclan;

lib/inventory/default.nix

@@ -2,11 +2,7 @@
   lib,
   clanLib,
 }:
-let
-  services = clanLib.callLib ./distributed-service/inventory-adapter.nix { };
-in
 {
-  inherit (services) mapInstances;
   inventoryModule = {
     _file = "clanLib.inventory.module";
     imports = [

lib/inventory/distributed-service/all-services-wrapper.nix

@@ -28,19 +28,15 @@ in
         elemType = submoduleWith {
           class = "clan.service";
           specialArgs = {
-            exports = config.exports;
             directory = directory;
             clanLib = specialArgs.clanLib;
+            exports = config.exports;
           };
           modules = [
             (
               { name, ... }:
               {
                 _module.args._ctx = [ name ];
-                _module.args.clanLib = specialArgs.clanLib;
-                _module.args.exports = config.exports;
-                _module.args.directory = directory;
-
               }
             )
             ./service-module.nix

lib/inventory/distributed-service/flake-module.nix

@@ -21,6 +21,7 @@ in
           ../../../flakeModules
           ../../../lib
           ../../../nixosModules/clanCore
+          ../../../nixosModules/machineModules
           ../../../machines
           ../../../inventory.json
           ../../../modules

lib/inventory/distributed-service/inventory-adapter.nix

@@ -1,171 +0,0 @@
-# Adapter function between the inventory.instances and the clan.service module
-#
-# Data flow:
-# - inventory.instances -> Adapter -> clan.service module -> Service Resources (i.e. NixosModules per Machine, Vars per Service, etc.)
-#
-# What this file does:
-#
-# - Resolves the [Module] to an actual module-path and imports it.
-# - Groups together all the same modules into a single import and creates all instances for it.
-# - Resolves the inventory tags into machines. Tags don't exist at the service level.
-#   Also combines the settings for 'machines' and 'tags'.
-{
-  lib,
-  clanLib,
-  ...
-}:
-{
-  mapInstances =
-    {
-      # This is used to resolve the module imports from 'flake.inputs'
-      flakeInputs,
-      # The clan inventory
-      inventory,
-      directory,
-      clanCoreModules,
-      prefix ? [ ],
-      exportsModule,
-    }:
-    let
-      # machineHasTag = machineName: tagName: lib.elem tagName inventory.machines.${machineName}.tags;
-
-      # map the instances into the module
-      importedModuleWithInstances = lib.mapAttrs (
-        instanceName: instance:
-        let
-          resolvedModule = clanLib.resolveModule {
-            moduleSpec = instance.module;
-            inherit flakeInputs clanCoreModules;
-          };
-
-          # Every instance includes machines via roles
-          # :: { client :: ... }
-          instanceRoles = lib.mapAttrs (
-            roleName: role:
-            let
-              resolvedMachines = clanLib.inventory.resolveTags {
-                members = {
-                  # Explicit members
-                  machines = lib.attrNames role.machines;
-                  # Resolved Members
-                  tags = lib.attrNames role.tags;
-                };
-                inherit (inventory) machines;
-                inherit instanceName roleName;
-              };
-            in
-            # instances.<instanceName>.roles.<roleName> =
-            # Remove "tags", they are resolved into "machines"
-            (removeAttrs role [ "tags" ])
-            // {
-              machines = lib.genAttrs resolvedMachines.machines (
-                machineName:
-                let
-                  machineSettings = instance.roles.${roleName}.machines.${machineName}.settings or { };
-                in
-                # TODO: tag settings
-                # Wait for this feature until option introspection for 'settings' is done.
-                # This might get too complex to handle otherwise.
-                # settingsViaTags = lib.filterAttrs (
-                #   tagName: _: machineHasTag machineName tagName
-                # ) instance.roles.${roleName}.tags;
-                {
-                  # TODO: Do we want to wrap settings with
-                  # setDefaultModuleLocation "inventory.instances.${instanceName}.roles.${roleName}.tags.${tagName}";
-                  settings = {
-                    imports = [
-                      machineSettings
-                    ]; # ++ lib.attrValues (lib.mapAttrs (_tagName: v: v.settings) settingsViaTags);
-                  };
-                }
-              );
-            }
-          ) instance.roles;
-        in
-        {
-          inherit (instance) module;
-          inherit resolvedModule instanceRoles;
-        }
-      ) inventory.instances or { };
-
-      # Group the instances by the module they resolve to
-      # This is necessary to evaluate the module in a single pass
-      # :: { <module.input>_<module.name> :: [ { name, value } ] }
-      # Since 'perMachine' needs access to all the instances we should include them as a whole
-      grouped = lib.foldlAttrs (
-        acc: instanceName: instance:
-        let
-          inputName = if instance.module.input == null then "<clan-core>" else instance.module.input;
-          id = inputName + "-" + instance.module.name;
-        in
-        acc
-        // {
-          ${id} = acc.${id} or [ ] ++ [
-            {
-              inherit instanceName instance;
-            }
-          ];
-        }
-      ) { } importedModuleWithInstances;
-
-      # servicesEval.config.mappedServices.self-A.result.final.jon.nixosModule
-      allMachines = lib.mapAttrs (machineName: _: {
-        # This is the list of nixosModules for each machine
-        machineImports = lib.foldlAttrs (
-          acc: _module_ident: serviceModule:
-          acc ++ [ serviceModule.result.final.${machineName}.nixosModule or { } ]
-        ) [ ] servicesEval.config.mappedServices;
-      }) inventory.machines or { };
-
-      evalServices =
-        { modules, prefix }:
-        lib.evalModules {
-          class = "clan";
-          specialArgs = {
-            inherit clanLib;
-            _ctx = prefix;
-          };
-          modules = [
-            (import ./all-services-wrapper.nix { inherit directory; })
-          ]
-          ++ modules;
-        };
-
-      servicesEval = evalServices {
-        inherit prefix;
-        modules = [
-          {
-            inherit exportsModule;
-            mappedServices = lib.mapAttrs (_module_ident: instances: {
-              imports = [
-                # Import the resolved module.
-                # i.e. clan.modules.admin
-                {
-                  options.module = lib.mkOption {
-                    type = lib.types.raw;
-                    default = (builtins.head instances).instance.module;
-                  };
-                }
-                (builtins.head instances).instance.resolvedModule
-              ] # Include all the instances that correlate to the resolved module
-              ++ (builtins.map (v: {
-                instances.${v.instanceName}.roles = v.instance.instanceRoles;
-              }) instances);
-            }) grouped;
-          }
-        ];
-      };
-      importedModulesEvaluated = servicesEval.config.mappedServices;
-
-    in
-    {
-      inherit
-        servicesEval
-        importedModuleWithInstances
-        # Exposed for testing
-        grouped
-        allMachines
-        importedModulesEvaluated
-        ;
-    };
-}

lib/inventory/distributed-service/service-module.nix

@@ -81,6 +81,7 @@ let
   applySettings =
     instanceName: instance:
     lib.mapAttrs (roleName: role: {
+      settings = config.instances.${instanceName}.roles.${roleName}.finalSettings.config;
       machines = lib.mapAttrs (machineName: _v: {
         settings =
           config.instances.${instanceName}.roles.${roleName}.machines.${machineName}.finalSettings.config;
@@ -158,6 +159,29 @@ in
                         (
                           { name, ... }@role:
                           {
+                            options.finalSettings = mkOption {
+                              default = evalMachineSettings instance.name role.name null role.config.settings { };
+                              type = types.raw;
+                              description = ''
+                                Final evaluated settings of the curent-machine
+
+                                This contains the merged and evaluated settings of the role interface,
+                                the role settings and the machine settings.
+
+                                Type: 'configuration' as returned by 'lib.evalModules'
+                              '';
+                              apply = lib.warn ''
+                                === WANRING ===
+                                'roles.<roleName>.settings' do not contain machine specific settings.
+
+                                Prefer `machines.<machineName>.settings` instead. (i.e `perInstance: roles.<roleName>.machines.<machineName>.settings`)
+
+                                If you have a use-case that requires access to the original role settings without machine overrides.
+                                Contact us via matrix (https://matrix.to/#/#clan:clan.lol) or file an issue: https://git.clan.lol
+
+                                This feature will be removed in the next release
+                              '';
+                            };
                             # instances.{instanceName}.roles.{roleName}.machines
                             options.machines = mkOption {
                               description = ''
@@ -859,7 +883,11 @@ in
                   instanceRes.nixosModule
                 ]
                 ++ (map (
-                  s: if builtins.typeOf s == "string" then "${directory}/${s}" else s
+                  s:
+                  if builtins.typeOf s == "string" then
+                    lib.warn "String types for 'extraModules' will be deprecated - ${s}" "${directory}/${s}"
+                  else
+                    lib.setDefaultModuleLocation "via inventory.instances.${instanceName}.roles.${roleName}" s
                 ) instanceCfg.roles.${roleName}.extraModules);
               };
             }

lib/inventory/distributed-service/tests/default.nix

@@ -4,36 +4,8 @@
   ...
 }:
 let
-  inherit (lib)
-    evalModules
-    ;
 
-  evalInventory =
-    m:
-    (evalModules {
-      # Static modules
-      modules = [
-        clanLib.inventory.inventoryModule
-        {
-          _file = "test file";
-          tags.all = [ ];
-          tags.nixos = [ ];
-          tags.darwin = [ ];
-        }
-        {
-          modules.test = { };
-        }
-        m
-      ];
-    }).config;
-
-  callInventoryAdapter =
-    inventoryModule:
-    let
-      inventory = evalInventory inventoryModule;
   flakeInputsFixture = {
-        self.clan.modules = inventoryModule.modules or { };
-        # Example upstream module
     upstream.clan.modules = {
       uzzi = {
         _class = "clan.service";
@@ -43,24 +15,42 @@ let
       };
     };
   };
-    in
-    clanLib.inventory.mapInstances {
-      directory = ./.;
-      clanCoreModules = { };
-      flakeInputs = flakeInputsFixture;
-      inherit inventory;
-      exportsModule = { };
+
+  createTestClan =
+    testClan:
+    let
+      res = clanLib.clan ({
+        # Static / mocked
+        specialArgs = {
+          clan-core = {
+            clan.modules = { };
           };
+        };
+        self.inputs = flakeInputsFixture // {
+          self.clan = res.config;
+        };
+        directory = ./.;
+        exportsModule = { };
+
+        imports = [
+          testClan
+        ];
+      });
+    in
+    res;
+
 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; };
+  settings = import ./settings.nix { inherit lib createTestClan; };
+  specialArgs = import ./specialArgs.nix { inherit lib createTestClan; };
+  resolve_module_spec = import ./import_module_spec.nix {
+    inherit lib createTestClan;
+  };
   test_simple =
     let
-      res = callInventoryAdapter {
+      res = createTestClan {
         # Authored module
         # A minimal module looks like this
         # It isn't exactly doing anything but it's a valid module that produces an output
@@ -71,7 +61,7 @@ in
           };
         };
         # User config
-        instances."instance_foo" = {
+        inventory.instances."instance_foo" = {
           module = {
             name = "simple-module";
           };
@@ -81,7 +71,7 @@ in
     {
       # Test that the module is mapped into the output
       # We might change the attribute name in the future
-      expr = res.importedModulesEvaluated ? "<clan-core>-simple-module";
+      expr = res.config._services.mappedServices ? "<clan-core>-simple-module";
       expected = true;
       inherit res;
     };
@@ -92,7 +82,7 @@ in
   # All instances should be included within one evaluation to make all of them available
   test_module_grouping =
     let
-      res = callInventoryAdapter {
+      res = createTestClan {
         # Authored module
         # A minimal module looks like this
         # It isn't exactly doing anything but it's a valid module that produces an output
@@ -112,18 +102,19 @@ in
 
           perMachine = { }: { };
         };
+
         # User config
-        instances."instance_foo" = {
+        inventory.instances."instance_foo" = {
           module = {
             name = "A";
           };
         };
-        instances."instance_bar" = {
+        inventory.instances."instance_bar" = {
           module = {
             name = "B";
           };
         };
-        instances."instance_baz" = {
+        inventory.instances."instance_baz" = {
           module = {
             name = "A";
           };
@@ -133,16 +124,16 @@ in
     {
       # Test that the module is mapped into the output
       # We might change the attribute name in the future
-      expr = lib.mapAttrs (_n: v: builtins.length v) res.grouped;
-      expected = {
-        "<clan-core>-A" = 2;
-        "<clan-core>-B" = 1;
-      };
+      expr = lib.attrNames res.config._services.mappedServices;
+      expected = [
+        "<clan-core>-A"
+        "<clan-core>-B"
+      ];
     };
 
   test_creates_all_instances =
     let
-      res = callInventoryAdapter {
+      res = createTestClan {
         # Authored module
         # A minimal module looks like this
         # It isn't exactly doing anything but it's a valid module that produces an output
@@ -154,6 +145,7 @@ in
 
           perMachine = { }: { };
         };
+        inventory = {
           instances."instance_foo" = {
             module = {
               name = "A";
@@ -173,11 +165,12 @@ in
             };
           };
         };
+      };
     in
     {
       # Test that the module is mapped into the output
       # We might change the attribute name in the future
-      expr = lib.attrNames res.importedModulesEvaluated.self-A.instances;
+      expr = lib.attrNames res.config._services.mappedServices.self-A.instances;
       expected = [
         "instance_bar"
         "instance_foo"
@@ -187,7 +180,7 @@ in
   # Membership via roles
   test_add_machines_directly =
     let
-      res = callInventoryAdapter {
+      res = createTestClan {
         # Authored module
         # A minimal module looks like this
         # It isn't exactly doing anything but it's a valid module that produces an output
@@ -202,6 +195,7 @@ in
 
           # perMachine = {}: {};
         };
+        inventory = {
           machines = {
             jon = { };
             sara = { };
@@ -229,11 +223,12 @@ in
             roles.peer.tags.all = { };
           };
         };
+      };
     in
     {
       # Test that the module is mapped into the output
       # We might change the attribute name in the future
-      expr = lib.attrNames res.importedModulesEvaluated.self-A.result.allMachines;
+      expr = lib.attrNames res.config._services.mappedServices.self-A.result.allMachines;
       expected = [
         "jon"
         "sara"
@@ -243,7 +238,7 @@ in
   # Membership via tags
   test_add_machines_via_tags =
     let
-      res = callInventoryAdapter {
+      res = createTestClan {
         # Authored module
         # A minimal module looks like this
         # It isn't exactly doing anything but it's a valid module that produces an output
@@ -257,6 +252,7 @@ in
 
           # perMachine = {}: {};
         };
+        inventory = {
           machines = {
             jon = {
               tags = [ "foo" ];
@@ -281,11 +277,12 @@ in
             roles.peer.tags.all = { };
           };
         };
+      };
     in
     {
       # Test that the module is mapped into the output
       # We might change the attribute name in the future
-      expr = lib.attrNames res.importedModulesEvaluated.self-A.result.allMachines;
+      expr = lib.attrNames res.config._services.mappedServices.self-A.result.allMachines;
       expected = [
         "jon"
         "sara"
@@ -293,6 +290,9 @@ in
     };
 
   machine_imports = import ./machine_imports.nix { inherit lib clanLib; };
-  per_machine_args = import ./per_machine_args.nix { inherit lib callInventoryAdapter; };
-  per_instance_args = import ./per_instance_args.nix { inherit lib callInventoryAdapter; };
+  per_machine_args = import ./per_machine_args.nix { inherit lib createTestClan; };
+  per_instance_args = import ./per_instance_args.nix {
+    inherit lib;
+    callInventoryAdapter = createTestClan;
+  };
 }

lib/inventory/distributed-service/tests/import_module_spec.nix

@@ -1,4 +1,4 @@
-{ callInventoryAdapter, ... }:
+{ createTestClan, ... }:
 let
   # Authored module
   # A minimal module looks like this
@@ -23,12 +23,15 @@ let
 
   resolve =
     spec:
-    callInventoryAdapter {
-      inherit modules machines;
+    createTestClan {
+      inherit modules;
+      inventory = {
+        inherit machines;
         instances."instance_foo" = {
           module = spec;
         };
       };
+    };
 in
 {
   test_import_local_module_by_name = {
@@ -36,25 +39,16 @@ in
       (resolve {
         name = "A";
         input = "self";
-      }).importedModuleWithInstances.instance_foo.resolvedModule;
-    expected = {
-      _class = "clan.service";
-      manifest = {
-        name = "network";
-      };
-    };
+      }).config._services.mappedServices.self-A.manifest.name;
+    expected = "network";
   };
   test_import_remote_module_by_name = {
     expr =
       (resolve {
         name = "uzzi";
         input = "upstream";
-      }).importedModuleWithInstances.instance_foo.resolvedModule;
-    expected = {
-      _class = "clan.service";
-      manifest = {
-        name = "uzzi-from-upstream";
-      };
-    };
+      }).config._services.mappedServices.upstream-uzzi.manifest.name;
+    expected = "uzzi-from-upstream";
+
   };
 }

lib/inventory/distributed-service/tests/per_instance_args.nix

@@ -58,7 +58,10 @@ let
     sara = { };
   };
   res = callInventoryAdapter {
-    inherit modules machines;
+    inherit modules;
+
+    inventory = {
+      inherit machines;
       instances."instance_foo" = {
         module = {
           name = "A";
@@ -93,6 +96,7 @@ let
         roles.peer.tags.all = { };
       };
     };
+  };
 
   /*
     1 { imports = [ { instanceName = "instance_foo"; machine = { name = "jon"; roles = [ "controller" "pe 1 null
@@ -105,9 +109,10 @@ in
 {
   # settings should evaluate
   test_per_instance_arguments = {
+    inherit res;
     expr = {
       instanceName =
-        res.importedModulesEvaluated.self-A.result.allRoles.peer.allInstances."instance_foo".allMachines.jon.passthru.instanceName;
+        res.config._services.mappedServices.self-A.result.allRoles.peer.allInstances."instance_foo".allMachines.jon.passthru.instanceName;
 
       # settings are specific.
       # Below we access:
@@ -115,11 +120,11 @@ in
       # roles = peer
       # machines = jon
       settings =
-        res.importedModulesEvaluated.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.settings;
+        res.config._services.mappedServices.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.settings;
       machine =
-        res.importedModulesEvaluated.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.machine;
+        res.config._services.mappedServices.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.machine;
       roles =
-        res.importedModulesEvaluated.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.roles;
+        res.config._services.mappedServices.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.roles;
     };
     expected = {
       instanceName = "instance_foo";
@@ -137,6 +142,7 @@ in
               settings = { };
             };
           };
+          settings = { };
         };
         peer = {
           machines = {
@@ -146,6 +152,9 @@ in
               };
             };
           };
+          settings = {
+            timeout = "foo-peer";
+          };
         };
       };
       settings = {
@@ -156,9 +165,9 @@ in
 
   # TODO: Cannot be tested like this anymore
   test_per_instance_settings_vendoring = {
-    x = res.importedModulesEvaluated.self-A;
+    x = res.config._services.mappedServices.self-A;
     expr =
-      res.importedModulesEvaluated.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.vendoredSettings;
+      res.config._services.mappedServices.self-A.result.allRoles.peer.allInstances.instance_foo.allMachines.jon.passthru.vendoredSettings;
     expected = {
       timeout = "config.thing";
     };

lib/inventory/distributed-service/tests/per_machine_args.nix

@@ -1,4 +1,4 @@
-{ lib, callInventoryAdapter }:
+{ lib, createTestClan }:
 let
   # Authored module
   # A minimal module looks like this
@@ -39,8 +39,11 @@ let
     jon = { };
     sara = { };
   };
-  res = callInventoryAdapter {
-    inherit modules machines;
+  res = createTestClan {
+    inherit modules;
+    inventory = {
+
+      inherit machines;
       instances."instance_foo" = {
         module = {
           name = "A";
@@ -70,6 +73,7 @@ let
         roles.peer.tags.all = { };
       };
     };
+  };
 in
 
 {
@@ -79,7 +83,7 @@ in
     inherit res;
     expr = {
       hasMachineSettings =
-        res.importedModulesEvaluated.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer.machines.jon
+        res.config._services.mappedServices.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer.machines.jon
         ? settings;
 
       # settings are specific.
@@ -88,10 +92,10 @@ in
       # roles = peer
       # machines = jon
       specificMachineSettings =
-        res.importedModulesEvaluated.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer.machines.jon.settings;
+        res.config._services.mappedServices.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer.machines.jon.settings;
 
       hasRoleSettings =
-        res.importedModulesEvaluated.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer
+        res.config._services.mappedServices.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer
         ? settings;
 
       # settings are specific.
@@ -100,21 +104,26 @@ in
       # roles = peer
       # machines = *
       specificRoleSettings =
-        res.importedModulesEvaluated.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer;
+        res.config._services.mappedServices.self-A.result.allMachines.jon.passthru.instances.instance_foo.roles.peer;
     };
-    expected = rec {
+    expected = {
       hasMachineSettings = true;
-      hasRoleSettings = false;
+      hasRoleSettings = true;
       specificMachineSettings = {
         timeout = "foo-peer-jon";
       };
       specificRoleSettings = {
         machines = {
           jon = {
-            settings = specificMachineSettings;
+            settings = {
+              timeout = "foo-peer-jon";
             };
           };
         };
+        settings = {
+          timeout = "foo-peer";
+        };
+      };
     };
   };
 }

lib/inventory/distributed-service/tests/settings.nix

@@ -1,6 +1,6 @@
-{ callInventoryAdapter, lib, ... }:
+{ createTestClan, lib, ... }:
 let
-  res = callInventoryAdapter {
+  res = createTestClan {
     modules."A" = {
       _class = "clan.service";
       manifest = {
@@ -21,6 +21,8 @@ let
           };
         };
     };
+    inventory = {
+
       machines = {
         jon = { };
         sara = { };
@@ -41,8 +43,9 @@ let
         roles.peer.machines.sara = { };
       };
     };
+  };
 
-  config = res.servicesEval.config.mappedServices.self-A;
+  config = res.config._services.mappedServices.self-A;
 
   #
   applySettings =

lib/inventory/distributed-service/tests/specialArgs.nix

@@ -1,6 +1,6 @@
-{ callInventoryAdapter, lib, ... }:
+{ createTestClan, lib, ... }:
 let
-  res = callInventoryAdapter {
+  res = createTestClan {
     modules."A" = m: {
       _class = "clan.service";
       config = {
@@ -14,6 +14,7 @@ let
         default = m;
       };
     };
+    inventory = {
       machines = {
         jon = { };
       };
@@ -25,8 +26,9 @@ let
         roles.peer.machines.jon = { };
       };
     };
+  };
 
-  specialArgs = lib.attrNames res.servicesEval.config.mappedServices.self-A.test.specialArgs;
+  specialArgs = lib.attrNames res.config._services.mappedServices.self-A.test.specialArgs;
 in
 {
   test_simple = {

lib/tests.nix

@@ -212,6 +212,36 @@ in
       };
     };
 
+  test_clan_check_simple_fail =
+    let
+      eval = clan {
+        checks.constFail = {
+          assertion = false;
+          message = "This is a constant failure";
+        };
+      };
+    in
+    {
+      result = eval;
+      expr = eval.config;
+      expectedError.type = "ThrownError";
+      expectedError.msg = "This is a constant failure";
+    };
+  test_clan_check_simple_pass =
+    let
+      eval = clan {
+        checks.constFail = {
+          assertion = true;
+          message = "This is a constant success";
+        };
+      };
+    in
+    {
+      result = eval;
+      expr = lib.seq eval.config 42;
+      expected = 42;
+    };
+
   test_get_var_machine =
     let
       varsLib = import ./vars.nix { };

modules/clan/checks.nix

@@ -0,0 +1,16 @@
+{ lib, nixpkgs, ... }:
+{
+  checks.minNixpkgsVersion = {
+    assertion = lib.versionAtLeast nixpkgs.lib.version "25.11";
+    message = ''
+      Nixpkgs version: ${nixpkgs.lib.version} is incompatible with clan-core. (>= 25.11 is recommended)
+      ---
+      Your version of 'nixpkgs' seems too old for clan-core.
+      Please read: https://docs.clan.lol/guides/nixpkgs-flake-input
+
+      You can ignore this check by setting:
+      clan.checks.minNixpkgsVersion.ignore = true;
+      ---
+    '';
+  };
+}

modules/clan/default.nix

@@ -1,3 +1,14 @@
+/**
+  Root 'clan' Module
+
+  Defines lib.clan and flake-parts.clan options
+  and all common logic for the 'clan' module.
+
+  - has Class _class = "clan"
+
+  - _module.args.clan-core: reference to clan-core flake
+  - _module.args.clanLib: reference to lib.clan function
+*/
 { clan-core }:
 {
   _class = "clan";
@@ -6,7 +17,9 @@
     inherit (clan-core) clanLib;
   };
   imports = [
+    ./top-level-interface.nix
     ./module.nix
-    ./interface.nix
+    ./distributed-services.nix
+    ./checks.nix
   ];
 }

modules/clan/distributed-services.nix

@@ -0,0 +1,163 @@
+{
+  lib,
+  clanLib,
+  config,
+  clan-core,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+  # Keep a reference to top-level
+  clanConfig = config;
+
+  inventory = clanConfig.inventory;
+  flakeInputs = clanConfig.self.inputs;
+  clanCoreModules = clan-core.clan.modules;
+
+  grouped = lib.foldlAttrs (
+    acc: instanceName: instance:
+    let
+      inputName = if instance.module.input == null then "<clan-core>" else instance.module.input;
+      id = inputName + "-" + instance.module.name;
+    in
+    acc
+    // {
+      ${id} = acc.${id} or [ ] ++ [
+        {
+          inherit instanceName instance;
+        }
+      ];
+    }
+  ) { } importedModuleWithInstances;
+
+  importedModuleWithInstances = lib.mapAttrs (
+    instanceName: instance:
+    let
+      resolvedModule = clanLib.resolveModule {
+        moduleSpec = instance.module;
+        inherit flakeInputs clanCoreModules;
+      };
+
+      # Every instance includes machines via roles
+      # :: { client :: ... }
+      instanceRoles = lib.mapAttrs (
+        roleName: role:
+        let
+          resolvedMachines = clanLib.inventory.resolveTags {
+            members = {
+              # Explicit members
+              machines = lib.attrNames role.machines;
+              # Resolved Members
+              tags = lib.attrNames role.tags;
+            };
+            inherit (inventory) machines;
+            inherit instanceName roleName;
+          };
+        in
+        # instances.<instanceName>.roles.<roleName> =
+        # Remove "tags", they are resolved into "machines"
+        (removeAttrs role [ "tags" ])
+        // {
+          machines = lib.genAttrs resolvedMachines.machines (
+            machineName:
+            let
+              machineSettings = instance.roles.${roleName}.machines.${machineName}.settings or { };
+            in
+            # TODO: tag settings
+            # Wait for this feature until option introspection for 'settings' is done.
+            # This might get too complex to handle otherwise.
+            # settingsViaTags = lib.filterAttrs (
+            #   tagName: _: machineHasTag machineName tagName
+            # ) instance.roles.${roleName}.tags;
+            {
+              # TODO: Do we want to wrap settings with
+              # setDefaultModuleLocation "inventory.instances.${instanceName}.roles.${roleName}.tags.${tagName}";
+              settings = {
+                imports = [
+                  machineSettings
+                ]; # ++ lib.attrValues (lib.mapAttrs (_tagName: v: v.settings) settingsViaTags);
+              };
+            }
+          );
+        }
+      ) instance.roles;
+    in
+    {
+      inherit (instance) module;
+      inherit resolvedModule instanceRoles;
+    }
+  ) inventory.instances or { };
+in
+{
+  _class = "clan";
+  options._services = mkOption {
+    visible = false;
+    description = ''
+      All service instances
+
+      !!! Danger "Internal API"
+        Do not rely on this API yet.
+
+        - Will be renamed to just 'services' in the future.
+        Once the name can be claimed again.
+        - Structure will change.
+
+        API will be declared as public after beeing simplified.
+    '';
+    type = types.submoduleWith {
+      # TODO: Remove specialArgs
+      specialArgs = {
+        inherit clanLib;
+      };
+      modules = [
+        (import ../../lib/inventory/distributed-service/all-services-wrapper.nix {
+          inherit (clanConfig) directory;
+        })
+        # Dependencies
+        {
+          exportsModule = clanConfig.exportsModule;
+        }
+        {
+          # TODO: Rename to "allServices"
+          # All services
+          mappedServices = lib.mapAttrs (_module_ident: instances: {
+            imports = [
+              # Import the resolved module.
+              # i.e. clan.modules.admin
+              {
+                options.module = lib.mkOption {
+                  type = lib.types.raw;
+                  default = (builtins.head instances).instance.module;
+                };
+              }
+              (builtins.head instances).instance.resolvedModule
+            ] # Include all the instances that correlate to the resolved module
+            ++ (builtins.map (v: {
+              instances.${v.instanceName}.roles = v.instance.instanceRoles;
+            }) instances);
+          }) grouped;
+        }
+      ];
+    };
+    default = { };
+  };
+  options._allMachines = mkOption {
+    internal = true;
+    type = types.raw;
+    default = lib.mapAttrs (machineName: _: {
+      # This is the list of nixosModules for each machine
+      machineImports = lib.foldlAttrs (
+        acc: _module_ident: serviceModule:
+        acc ++ [ serviceModule.result.final.${machineName}.nixosModule or { } ]
+      ) [ ] config._services.mappedServices;
+    }) inventory.machines or { };
+  };
+
+  config = {
+    clanInternals.inventoryClass.machines = config._allMachines;
+    # clanInternals.inventoryClass.distributedServices = config._services;
+
+    # Exports from distributed services
+    exports = config._services.exports;
+  };
+}

modules/clan/eval-docs.nix

@@ -3,12 +3,16 @@
   lib,
   clanModule,
   clanLib,
+  clan-core,
 }:
 let
   eval = lib.evalModules {
     modules = [
       clanModule
     ];
+    specialArgs = {
+      self = clan-core;
+    };
   };
 
   evalDocs = pkgs.nixosOptionsDoc {

modules/clan/flake-module.nix

@@ -12,6 +12,7 @@ in
     }:
     let
       jsonDocs = import ./eval-docs.nix {
+        clan-core = self;
         inherit
           pkgs
           lib

modules/clan/module.nix

@@ -100,7 +100,7 @@ let
           _: machine:
           machine.extendModules {
             modules = [
-              (lib.modules.importApply ../machineModules/overridePkgs.nix {
+              (lib.modules.importApply ../../nixosModules/machineModules/overridePkgs.nix {
                 pkgs = pkgsFor.${system};
               })
             ];
@@ -167,6 +167,9 @@ in
           { ... }@args:
           let
             _class =
+              # _class was added in https://github.com/NixOS/nixpkgs/pull/395141
+              # Clan relies on it to determine which modules to load
+              # people need to use at least that version of nixpkgs
               args._class or (throw ''
                 Your version of nixpkgs is incompatible with the latest clan.
                 Please update nixpkgs input to the latest nixos-unstable or nixpkgs-unstable.
@@ -176,7 +179,7 @@ in
           in
           {
             imports = [
-              (lib.modules.importApply ../machineModules/forName.nix {
+              (lib.modules.importApply ../../nixosModules/machineModules/forName.nix {
                 inherit (config.inventory) meta;
                 inherit
                   name
@@ -216,12 +219,22 @@ in
     inherit nixosConfigurations;
     inherit darwinConfigurations;
 
-    exports = config.clanInternals.inventoryClass.distributedServices.servicesEval.config.exports;
-
     clanInternals = {
       inventoryClass =
         let
           flakeInputs = config.self.inputs;
+          # Compute the relative directory path
+          selfStr = toString config.self;
+          dirStr = toString directory;
+          relativeDirectory =
+            if selfStr == dirStr then
+              ""
+            else if lib.hasPrefix selfStr dirStr then
+              lib.removePrefix (selfStr + "/") dirStr
+            else
+              # This shouldn't happen in normal usage, but can occur when
+              # the flake is copied (e.g., in tests). Fall back to empty string.
+              "";
         in
         {
           _module.args = {
@@ -230,25 +243,18 @@ in
           imports = [
             ../inventoryClass/default.nix
             {
-              inherit inventory directory flakeInputs;
-              exportsModule = config.exportsModule;
-            }
-            (
-              { config, ... }:
-              {
-                staticModules = clan-core.clan.modules;
-
-                distributedServices = clanLib.inventory.mapInstances {
-                  inherit (config)
+              inherit
                 inventory
                 directory
                 flakeInputs
-                    exportsModule
+                relativeDirectory
                 ;
-                  clanCoreModules = clan-core.clan.modules;
-                  prefix = [ "distributedServices" ];
-                };
-                machines = config.distributedServices.allMachines;
+              exportsModule = config.exportsModule;
+            }
+            (
+              { ... }:
+              {
+                staticModules = clan-core.clan.modules;
               }
             )
           ];

modules/clan/templates.nix

@@ -1,3 +1,28 @@
+/**
+  The templates submodule
+
+  'clan.templates'
+
+  Different kinds supported:
+
+  - clan templates: 'clan.templates.clan'
+  - disko templates: 'clan.templates.disko'
+  - machine templates: 'clan.templates.machine'
+
+  A template has the form:
+
+  ```nix
+  {
+    description: string; # short summary what the template contains
+    path: path; # path to the template
+  }
+  ```
+
+  The clan API copies the template from the given 'path'
+  into a target folder. For example,
+
+  `./machines/<machine-name>` for 'machine' templates.
+*/
 {
   lib,
   ...

modules/inventoryClass/default.nix

@@ -67,9 +67,6 @@ in
       type = types.raw;
     };
 
-    distributedServices = mkOption {
-      type = types.raw;
-    };
     inventory = mkOption {
       type = types.raw;
     };
@@ -81,6 +78,14 @@ in
     directory = mkOption {
       type = types.path;
     };
+    relativeDirectory = mkOption {
+      type = types.str;
+      internal = true;
+      description = ''
+        The relative directory path from the flake root to the clan directory.
+        Empty string if directory equals the flake root.
+      '';
+    };
     machines = mkOption {
       type = types.attrsOf (submodule ({
         options = {

modules/inventoryClass/role.nix

@@ -44,12 +44,6 @@ in
       description = ''
         List of additionally imported `.nix` expressions.
 
-        Supported types:
-
-        - **Strings**: Interpreted relative to the 'directory' passed to `lib.clan`.
-        - **Paths**: should be relative to the current file.
-        - **Any**: Nix expression must be serializable to JSON.
-
         !!! Note
             **The import only happens if the machine is part of the service or role.**
 
@@ -74,7 +68,7 @@ in
             ```
       '';
       default = [ ];
-      type = types.listOf types.deferredModule;
+      type = types.listOf types.raw;
     };
   };
 }

nixosModules/flake-module.nix

@@ -18,7 +18,7 @@ let
         inputs.data-mesher.nixosModules.data-mesher
       ];
       config = {
-        clan.core.clanPkgs = lib.mkDefault self.packages.${pkgs.hostPlatform.system};
+        clan.core.clanPkgs = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system};
       };
     };
 in

nixosModules/installer/zfs-latest.nix

@@ -30,5 +30,5 @@ let
 in
 {
   # Note this might jump back and worth as kernel get added or removed.
-  boot.kernelPackages = lib.mkIf (lib.meta.availableOn pkgs.hostPlatform pkgs.zfs) latestKernelPackage;
+  boot.kernelPackages = lib.mkIf (lib.meta.availableOn pkgs.stdenv.hostPlatform pkgs.zfs) latestKernelPackage;
 }

nixosModules/machineModules/forName.nix

@@ -3,6 +3,7 @@
   directory,
   meta,
 }:
+# The following is a nixos/darwin module
 {
   _class,
   lib,

pkgs/clan-cli/clan_cli/vars/secret_modules/password_store.py

@@ -245,7 +245,7 @@ class SecretStore(StoreBase):
                             output_dir / "activation" / generator.name / file.name
                         )
                         out_file.parent.mkdir(parents=True, exist_ok=True)
-                        out_file.write_bytes(self.get(generator, file.name))
+                        out_file.write_bytes(file.value)
         if "partitioning" in phases:
             for generator in vars_generators:
                 for file in generator.files:
@@ -254,7 +254,7 @@ class SecretStore(StoreBase):
                             output_dir / "partitioning" / generator.name / file.name
                         )
                         out_file.parent.mkdir(parents=True, exist_ok=True)
-                        out_file.write_bytes(self.get(generator, file.name))
+                        out_file.write_bytes(file.value)
 
         hash_data = self.generate_hash(machine)
         if hash_data:

pkgs/clan-cli/clan_cli/vars/secret_modules/sops.py

@@ -246,7 +246,7 @@ class SecretStore(StoreBase):
                         )
                         # chmod after in case it doesn't have u+w
                         target_path.touch(mode=0o600)
-                        target_path.write_bytes(self.get(generator, file.name))
+                        target_path.write_bytes(file.value)
                         target_path.chmod(file.mode)
 
         if "partitioning" in phases:
@@ -260,7 +260,7 @@ class SecretStore(StoreBase):
                         )
                         # chmod after in case it doesn't have u+w
                         target_path.touch(mode=0o600)
-                        target_path.write_bytes(self.get(generator, file.name))
+                        target_path.write_bytes(file.value)
                         target_path.chmod(file.mode)
 
     @override

pkgs/clan-cli/clan_lib/api/__init__.py

@@ -243,7 +243,11 @@ API.register(get_system_file)
             if "oneOf" not in return_type:
                 msg = (
                     f"Return type of function '{name}' is not a union type. Expected a union of Success and Error types."
-                    # @DavHau: no idea wy exactly this leads to the "oneOf" ot being present, but this should help
+                    # If the SuccessData type is unsupported it was dropped by Union narrowing.
+                    # This is probably an antifeature
+                    # Introduced because run_generator wanted to use:
+                    # Callable[[Generator], dict[str, str]]
+                    # In its function signature.
                     "Hint: When using dataclasses as return types, ensure they don't contain public fields with non-serializable types"
                 )
                 raise JSchemaTypeError(msg)

pkgs/clan-cli/clan_lib/dirs/__init__.py

@@ -156,14 +156,28 @@ def vm_state_dir(flake_url: str, vm_name: str) -> Path:
 
 
 def machines_dir(flake: "Flake") -> Path:
+    # Determine the base path
     if flake.is_local:
-        return flake.path / "machines"
-
+        base_path = flake.path
+    else:
         store_path = flake.store_path
         if store_path is None:
             msg = "Invalid flake object. Doesn't have a store path"
             raise ClanError(msg)
-    return Path(store_path) / "machines"
+        base_path = Path(store_path)
+
+    # Get the clan directory configuration from Nix
+    # This is computed in Nix where store paths are consistent
+    # Returns "" if no custom directory is set
+    # Fall back to "" if the option doesn't exist (backwards compatibility)
+    try:
+        clan_dir = flake.select("clanInternals.inventoryClass.relativeDirectory")
+    except ClanError:
+        # Option doesn't exist in older clan-core versions
+        # Assume no custom directory
+        clan_dir = ""
+
+    return base_path / clan_dir / "machines"
 
 
 def specific_machine_dir(machine: "MachineSpecProtocol") -> Path:

pkgs/clan-cli/clan_lib/flake/flake.py

@@ -211,7 +211,7 @@ class ClanSelectError(ClanError):
 
     def __str__(self) -> str:
         if self.description:
-            return f"{self.msg}  Reason: {self.description}"
+            return f"{self.msg}  Reason: {self.description}. Use flag '--debug' to see full nix trace."
         return self.msg
 
     def __repr__(self) -> str:

pkgs/clan-cli/clan_lib/llm/container_test.py

@@ -5,15 +5,18 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 from unittest.mock import MagicMock, patch
 
+import clan_lib.llm.llm_types
 import pytest
 from clan_lib.flake.flake import Flake
+from clan_lib.llm.llm_types import ModelConfig
 from clan_lib.llm.orchestrator import get_llm_turn
 from clan_lib.llm.service import create_llm_model, run_llm_service
 from clan_lib.service_runner import create_service_manager
 
 if TYPE_CHECKING:
     from clan_lib.llm.llm_types import ChatResult
-    from clan_lib.llm.schemas import ChatMessage, SessionState
+    from clan_lib.llm.schemas import SessionState
+import platform
 
 
 def get_current_mode(session_state: "SessionState") -> str:
@@ -168,28 +171,54 @@ def llm_service() -> Iterator[None]:
             service_manager.stop_service("ollama")
 
 
-def execute_multi_turn_workflow(
-    user_request: str,
-    flake: Flake | MagicMock,
-    conversation_history: list["ChatMessage"] | None = None,
-    provider: str = "ollama",
-    session_state: "SessionState | None" = None,
-) -> "ChatResult":
-    """Execute the multi-turn workflow, auto-executing all pending operations.
+@pytest.mark.service_runner
+@pytest.mark.usefixtures("mock_nix_shell", "llm_service")
+def test_full_conversation_flow(mock_flake: MagicMock) -> None:
+    """Test the complete conversation flow by manually calling get_llm_turn at each step.
 
-    This simulates the behavior of the CLI auto-execute loop in workflow.py.
+    This test verifies:
+    - State transitions through discovery -> readme_fetch -> service_selection -> final_decision
+    - Each step returns the correct next_action
+    - Conversation history is preserved across turns
+    - Session state is correctly maintained
     """
+    flake = mock_flake
+    trace_file = Path("~/.ollama/container_test_llm_trace.json").expanduser()
+    trace_file.unlink(missing_ok=True)  # Start fresh
+    provider = "ollama"
+
+    # Override DEFAULT_MODELS with 4-minute timeouts for container tests
+    clan_lib.llm.llm_types.DEFAULT_MODELS = {
+        "ollama": ModelConfig(
+            name="qwen3:4b-instruct",
+            provider="ollama",
+            timeout=300,  # set inference timeout to 5 minutes as CI may be slow
+            temperature=0,  # set randomness to 0 for consistent test results
+        ),
+    }
+
+    # ========== STEP 1: Initial request (should return next_action for discovery) ==========
+    print_separator("STEP 1: Initial Request", char="=", width=80)
     result = get_llm_turn(
-        user_request=user_request,
+        user_request="What VPN options do I have?",
         flake=flake,
-        conversation_history=conversation_history,
         provider=provider,  # type: ignore[arg-type]
-        session_state=session_state,
         execute_next_action=False,
+        trace_file=trace_file,
     )
 
-    # Auto-execute any pending operations
-    while result.next_action:
+    # Should have next_action for discovery phase
+    assert result.next_action is not None, "Should have next_action for discovery"
+    assert result.next_action["type"] == "discovery"
+    assert result.requires_user_response is False
+    assert len(result.proposed_instances) == 0
+    assert "pending_discovery" in result.session_state
+    print(f"  Next Action: {result.next_action['type']}")
+    print(f"  Description: {result.next_action['description']}")
+    print_meta_info(result, turn=1, phase="Initial Request")
+
+    # ========== STEP 2: Execute discovery (should return next_action for readme_fetch) ==========
+    print_separator("STEP 2: Execute Discovery", char="=", width=80)
     result = get_llm_turn(
         user_request="",
         flake=flake,
@@ -197,187 +226,100 @@ def execute_multi_turn_workflow(
         provider=provider,  # type: ignore[arg-type]
         session_state=result.session_state,
         execute_next_action=True,
+        trace_file=trace_file,
     )
 
-    return result
-
-
-@pytest.mark.service_runner
-@pytest.mark.usefixtures("mock_nix_shell", "llm_service")
-def test_full_conversation_flow(mock_flake: MagicMock) -> None:
-    """Comprehensive test that exercises the complete conversation flow with the actual LLM service.
-
-    This test simulates a realistic multi-turn conversation that covers:
-    - Discovery phase: Initial request and LLM gathering information
-    - Service selection phase: User choosing from available options
-    - Final decision phase: Configuring the selected service with specific parameters
-    - State transitions: pending_service_selection -> pending_final_decision -> completion
-    - Conversation history preservation across all turns
-    - Error handling and edge cases
-    """
-    flake = mock_flake
-    # ========== TURN 1: Discovery Phase - Initial vague request ==========
-    print_separator("TURN 1: Discovery Phase", char="=", width=80)
-    result = execute_multi_turn_workflow(
-        user_request="What VPN options do I have?",
-        flake=flake,
-        provider="ollama",
-    )
-
-    # Verify discovery phase behavior
-    assert result.requires_user_response is True, (
-        "Should require user response in discovery"
-    )
-    assert len(result.conversation_history) >= 2, (
-        "Should have user + assistant messages"
-    )
-    assert result.conversation_history[0]["role"] == "user"
-    assert result.conversation_history[0]["content"] == "What VPN options do I have?"
-    assert result.conversation_history[-1]["role"] == "assistant"
-    assert len(result.assistant_message) > 0, "Assistant should provide a response"
-
-    # After multi-turn execution, we may have either:
-    # - pending_service_selection (if LLM provided options and is waiting for choice)
-    # - pending_final_decision (if LLM directly selected a service)
-    # - no pending state (if LLM asked a clarifying question)
-
-    # No instances yet
-    assert len(result.proposed_instances) == 0
-    assert result.error is None
-
-    print_chat_exchange(
-        "What VPN options do I have?", result.assistant_message, result.session_state
-    )
-    print_meta_info(result, turn=1, phase="Discovery")
-
-    # ========== TURN 2: Service Selection Phase - User makes a choice ==========
-    print_separator("TURN 2: Service Selection", char="=", width=80)
-    user_msg_2 = "I'll use ZeroTier please"
-    result = execute_multi_turn_workflow(
-        user_request=user_msg_2,
-        flake=flake,
-        conversation_history=list(result.conversation_history),
-        provider="ollama",
-        session_state=result.session_state,
-    )
-
-    # Verify conversation history growth and preservation
-    assert len(result.conversation_history) > 2, "History should grow"
-    assert result.conversation_history[0]["content"] == "What VPN options do I have?"
-    assert result.conversation_history[2]["content"] == "I'll use ZeroTier please"
-
-    # Should either ask for configuration details or provide direct config
-    # Most likely will ask for more details (pending_final_decision)
-    if result.requires_user_response:
-        # LLM is asking for configuration details
+    # Should have next_action for readme fetch OR a clarifying question
+    if result.next_action:
+        assert result.next_action["type"] == "fetch_readmes"
+        assert "pending_readme_fetch" in result.session_state
+        print(f"  Next Action: {result.next_action['type']}")
+        print(f"  Description: {result.next_action['description']}")
+    else:
+        # LLM asked a clarifying question
+        assert result.requires_user_response is True
         assert len(result.assistant_message) > 0
-        # Should transition to final decision phase
-        if "pending_final_decision" not in result.session_state:
-            # Might still be in service selection asking clarifications
-            assert "pending_service_selection" in result.session_state
-    else:
-        # LLM provided configuration immediately (less likely)
-        assert len(result.proposed_instances) > 0
-        assert result.proposed_instances[0]["module"]["name"] == "zerotier"
+        print(f"  Assistant Message: {result.assistant_message[:100]}...")
+    print_meta_info(result, turn=2, phase="Discovery Executed")
 
-    print_chat_exchange(user_msg_2, result.assistant_message, result.session_state)
-    print_meta_info(result, turn=2, phase="Service Selection")
-
-    # ========== Continue conversation until we reach final decision or completion ==========
-    max_turns = 10
-    turn_count = 2
-
-    while result.requires_user_response and turn_count < max_turns:
-        turn_count += 1
-
-        # Determine appropriate response based on current state
-        if "pending_service_selection" in result.session_state:
-            # Still selecting service
-            user_request = "Yes, ZeroTier"
-            phase = "Service Selection (continued)"
-        elif "pending_final_decision" in result.session_state:
-            # Configuring the service
-            user_request = "Set up gchq-local as controller, qube-email as moon, and wintux as peer"
-            phase = "Final Configuration"
-        else:
-            # Generic continuation
-            user_request = "Yes, that sounds good. Use gchq-local as controller."
-            phase = "Continuing Conversation"
-
-        print_separator(f"TURN {turn_count}: {phase}", char="=", width=80)
-
-        result = execute_multi_turn_workflow(
-            user_request=user_request,
+    # ========== STEP 3: Execute readme fetch (if applicable) ==========
+    if result.next_action and result.next_action["type"] == "fetch_readmes":
+        print_separator("STEP 3: Execute Readme Fetch", char="=", width=80)
+        result = get_llm_turn(
+            user_request="",
             flake=flake,
             conversation_history=list(result.conversation_history),
-            provider="ollama",
+            provider=provider,  # type: ignore[arg-type]
             session_state=result.session_state,
+            execute_next_action=True,
+            trace_file=trace_file,
         )
 
-        # Verify conversation history continues to grow
-        assert len(result.conversation_history) == (turn_count * 2), (
-            f"History should have {turn_count * 2} messages (turn {turn_count})"
+        # Should have next_action for service selection
+        assert result.next_action is not None
+        assert result.next_action["type"] == "service_selection"
+        assert "pending_service_selection" in result.session_state
+        print(f"  Next Action: {result.next_action['type']}")
+        print(f"  Description: {result.next_action['description']}")
+        print_meta_info(result, turn=3, phase="Readme Fetch Executed")
+
+        if platform.machine() == "aarch64":
+            pytest.skip(
+                "aarch64 detected: skipping readme/service-selection and final step for performance reasons"
             )
 
-        # Verify history preservation
-        assert (
-            result.conversation_history[0]["content"] == "What VPN options do I have?"
+        # ========== STEP 4: Execute service selection ==========
+        print_separator("STEP 4: Execute Service Selection", char="=", width=80)
+        result = get_llm_turn(
+            user_request="I want ZeroTier.",
+            flake=flake,
+            conversation_history=list(result.conversation_history),
+            provider=provider,  # type: ignore[arg-type]
+            session_state=result.session_state,
+            execute_next_action=True,
+            trace_file=trace_file,
         )
 
-        print_chat_exchange(
-            user_request, result.assistant_message, result.session_state
-        )
-        print_meta_info(result, turn=turn_count, phase=phase)
-
-        # Check for completion
-        if not result.requires_user_response:
-            print_separator("CONVERSATION COMPLETED", char="=", width=80)
-            break
-
-    # ========== Final Verification ==========
-    print_separator("FINAL VERIFICATION", char="=", width=80)
-    assert turn_count < max_turns, f"Conversation took too many turns ({turn_count})"
-
-    # If conversation completed, verify we have valid configuration
-    if not result.requires_user_response:
-        assert len(result.proposed_instances) > 0, (
-            "Should have at least one proposed instance"
-        )
-        instance = result.proposed_instances[0]
-
-        # Verify instance structure
-        assert "module" in instance
-        assert "name" in instance["module"]
-        assert instance["module"]["name"] in [
-            "zerotier",
-            "wireguard",
-            "yggdrasil",
-            "mycelium",
-        ]
-
-        # Should not be in pending state anymore
-        assert "pending_service_selection" not in result.session_state
-        assert "pending_final_decision" not in result.session_state
-
-        assert result.error is None, f"Should not have error: {result.error}"
-
-        print_separator("FINAL SUMMARY", char="-", width=80, double=False)
-        print("  Status:                SUCCESS")
-        print(f"  Module Name:           {instance['module']['name']}")
-        print(f"  Total Turns:           {turn_count}")
-        print(f"  Final History Length:  {len(result.conversation_history)} messages")
-        if "roles" in instance:
-            roles_list = ", ".join(instance["roles"].keys())
-            print(f"  Configuration Roles:   {roles_list}")
-        print("  Errors:                None")
-        print("-" * 80)
+        # Should either have next_action for final_decision OR a clarifying question
+        if result.next_action:
+            assert result.next_action["type"] == "final_decision"
+            assert "pending_final_decision" in result.session_state
+            print(f"  Next Action: {result.next_action['type']}")
+            print(f"  Description: {result.next_action['description']}")
         else:
-        # Conversation didn't complete but should have made progress
-        assert len(result.conversation_history) > 2
-        assert result.error is None
-        print_separator("FINAL SUMMARY", char="-", width=80, double=False)
-        print("  Status:                IN PROGRESS")
-        print(f"  Total Turns:           {turn_count}")
-        print(f"  Current State:         {list(result.session_state.keys())}")
-        print(f"  History Length:        {len(result.conversation_history)} messages")
-        print("-" * 80)
+            # LLM asked a clarifying question during service selection
+            assert result.requires_user_response is True
+            assert len(result.assistant_message) > 0
+            print(f"  Assistant Message: {result.assistant_message[:100]}...")
+        print_meta_info(result, turn=4, phase="Service Selection Executed")
+
+        # ========== STEP 5: Execute final decision (if applicable) ==========
+        if result.next_action and result.next_action["type"] == "final_decision":
+            print_separator("STEP 5: Execute Final Decision", char="=", width=80)
+            result = get_llm_turn(
+                user_request="",
+                flake=flake,
+                conversation_history=list(result.conversation_history),
+                provider=provider,  # type: ignore[arg-type]
+                session_state=result.session_state,
+                execute_next_action=True,
+                trace_file=trace_file,
+            )
+
+            # Should either have proposed_instances OR ask a clarifying question
+            if result.proposed_instances:
+                assert len(result.proposed_instances) > 0
+                assert result.next_action is None
+                print(f"  Proposed Instances: {len(result.proposed_instances)}")
+                for inst in result.proposed_instances:
+                    print(f"    - {inst['module']['name']}")
+            else:
+                # LLM asked a clarifying question
+                assert result.requires_user_response is True
+                assert len(result.assistant_message) > 0
+                print(f"  Assistant Message: {result.assistant_message[:100]}...")
+            print_meta_info(result, turn=5, phase="Final Decision Executed")
+
+    # Verify conversation history has grown
+    assert len(result.conversation_history) > 0
+    assert result.conversation_history[0]["content"] == "What VPN options do I have?"

pkgs/clan-cli/clan_lib/llm/endpoints.py

@@ -149,6 +149,7 @@ def call_openai_api(
     trace_file: Path | None = None,
     stage: str = "unknown",
     trace_metadata: dict[str, Any] | None = None,
+    temperature: float | None = None,
 ) -> OpenAIChatCompletionResponse:
     """Call the OpenAI API for chat completion.
 
@@ -160,6 +161,7 @@ def call_openai_api(
         trace_file: Optional path to write trace entries for debugging
         stage: Stage name for trace entries (default: "unknown")
         trace_metadata: Optional metadata to include in trace entries
+        temperature: Sampling temperature (default: None = use API default)
 
     Returns:
         The parsed JSON response from the API
@@ -178,6 +180,8 @@ def call_openai_api(
         "messages": messages,
         "tools": list(tools),
     }
+    if temperature is not None:
+        payload["temperature"] = temperature
     _debug_log_request("openai", messages, tools)
     url = "https://api.openai.com/v1/chat/completions"
     headers = {
@@ -256,6 +260,7 @@ def call_claude_api(
     trace_file: Path | None = None,
     stage: str = "unknown",
     trace_metadata: dict[str, Any] | None = None,
+    temperature: float | None = None,
 ) -> OpenAIChatCompletionResponse:
     """Call the Claude API (via OpenAI-compatible endpoint) for chat completion.
 
@@ -268,6 +273,7 @@ def call_claude_api(
         trace_file: Optional path to write trace entries for debugging
         stage: Stage name for trace entries (default: "unknown")
         trace_metadata: Optional metadata to include in trace entries
+        temperature: Sampling temperature (default: None = use API default)
 
     Returns:
         The parsed JSON response from the API
@@ -293,6 +299,8 @@ def call_claude_api(
         "messages": messages,
         "tools": list(tools),
     }
+    if temperature is not None:
+        payload["temperature"] = temperature
     _debug_log_request("claude", messages, tools)
 
     url = f"{base_url}chat/completions"
@@ -372,6 +380,7 @@ def call_ollama_api(
     stage: str = "unknown",
     max_tokens: int | None = None,
     trace_metadata: dict[str, Any] | None = None,
+    temperature: float | None = None,
 ) -> OllamaChatResponse:
     """Call the Ollama API for chat completion.
 
@@ -384,6 +393,7 @@ def call_ollama_api(
         stage: Stage name for trace entries (default: "unknown")
         max_tokens: Maximum number of tokens to generate (default: None = unlimited)
         trace_metadata: Optional metadata to include in trace entries
+        temperature: Sampling temperature (default: None = use API default)
 
     Returns:
         The parsed JSON response from the API
@@ -399,9 +409,14 @@ def call_ollama_api(
         "tools": list(tools),
     }
 
-    # Add max_tokens limit if specified
+    # Add options for max_tokens and temperature if specified
+    options: dict[str, int | float] = {}
     if max_tokens is not None:
-        payload["options"] = {"num_predict": max_tokens}  # type: ignore[typeddict-item]
+        options["num_predict"] = max_tokens
+    if temperature is not None:
+        options["temperature"] = temperature
+    if options:
+        payload["options"] = options  # type: ignore[typeddict-item]
     _debug_log_request("ollama", messages, tools)
     url = "http://localhost:11434/api/chat"
 

pkgs/clan-cli/clan_lib/llm/llm_types.py

@@ -73,19 +73,21 @@ class ModelConfig:
         name: The model identifier/name
         provider: The LLM provider
         timeout: Request timeout in seconds (default: 120)
+        temperature: Sampling temperature for the model (default: None = use API default)
 
     """
 
     name: str
     provider: Literal["openai", "ollama", "claude"]
     timeout: int = 120
+    temperature: float | None = None
 
 
 # Default model configurations for each provider
 DEFAULT_MODELS: dict[Literal["openai", "ollama", "claude"], ModelConfig] = {
     "openai": ModelConfig(name="gpt-4o", provider="openai", timeout=60),
     "claude": ModelConfig(name="claude-sonnet-4-5", provider="claude", timeout=60),
-    "ollama": ModelConfig(name="qwen3:4b-instruct", provider="ollama", timeout=120),
+    "ollama": ModelConfig(name="qwen3:4b-instruct", provider="ollama", timeout=180),
 }
 
 

pkgs/clan-cli/clan_lib/llm/phases.py

@@ -100,6 +100,7 @@ def get_llm_discovery_phase(
             trace_file=trace_file,
             stage="discovery",
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_openai_response(
             openai_response, provider="openai"
@@ -113,6 +114,7 @@ def get_llm_discovery_phase(
             trace_file=trace_file,
             stage="discovery",
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_openai_response(
             claude_response, provider="claude"
@@ -127,6 +129,7 @@ def get_llm_discovery_phase(
             stage="discovery",
             max_tokens=300,  # Limit output for discovery phase (get_readme calls or short question)
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_ollama_response(
             ollama_response, provider="ollama"
@@ -249,6 +252,7 @@ def get_llm_service_selection(
             trace_file=trace_file,
             stage="select_service",
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_openai_response(
             openai_response, provider="openai"
@@ -262,6 +266,7 @@ def get_llm_service_selection(
             trace_file=trace_file,
             stage="select_service",
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_openai_response(
             claude_response, provider="claude"
@@ -276,6 +281,7 @@ def get_llm_service_selection(
             stage="select_service",
             max_tokens=600,  # Allow space for summary
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_ollama_response(
             ollama_response, provider="ollama"
@@ -447,6 +453,7 @@ def get_llm_final_decision(
             trace_file=trace_file,
             stage="final_decision",
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_openai_response(
             openai_response, provider="openai"
@@ -462,6 +469,7 @@ def get_llm_final_decision(
             trace_file=trace_file,
             stage="final_decision",
             trace_metadata=trace_metadata,
+            temperature=model_config.temperature,
         )
         function_calls, message_content = parse_openai_response(
             claude_response, provider="claude"
@@ -477,6 +485,7 @@ def get_llm_final_decision(
         stage="final_decision",
         max_tokens=500,  # Limit output to prevent excessive verbosity
         trace_metadata=trace_metadata,
+        temperature=model_config.temperature,
     )
     function_calls, message_content = parse_ollama_response(
         ollama_response, provider="ollama"

pkgs/clan-cli/clan_lib/llm/schemas.py

@@ -231,6 +231,7 @@ class ChatCompletionRequestPayload(TypedDict, total=False):
     messages: list[ChatMessage]
     tools: list[ToolDefinition]
     stream: NotRequired[bool]
+    temperature: NotRequired[float]
 
 
 @dataclass(frozen=True)

pkgs/clan-cli/clan_lib/nix_models/clan.py

@@ -28,13 +28,11 @@ class InventoryInstanceRoleMachine(TypedDict):
 
 
 
-InventoryInstanceRoleExtramodulesType = list[Unknown]
 InventoryInstanceRoleMachinesType = dict[str, InventoryInstanceRoleMachine]
 InventoryInstanceRoleSettingsType = Unknown
 InventoryInstanceRoleTagsType = dict[str, Any] | list[str]
 
 class InventoryInstanceRole(TypedDict):
-    extraModules: NotRequired[InventoryInstanceRoleExtramodulesType]
     machines: NotRequired[InventoryInstanceRoleMachinesType]
     settings: NotRequired[InventoryInstanceRoleSettingsType]
     tags: NotRequired[InventoryInstanceRoleTagsType]

pkgs/clan-cli/clan_lib/service_runner/systemd_user.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Literal, TypedDict
 
-from clan_lib.cmd import RunOpts, run
+from clan_lib.cmd import Log, RunOpts, run
 from clan_lib.errors import ClanError
 
 if TYPE_CHECKING:
@@ -70,7 +70,7 @@ class SystemdUserService:
         """Run systemctl command with --user flag."""
         return run(
             ["systemctl", "--user", action, f"{service_name}.service"],
-            RunOpts(check=False),
+            RunOpts(check=False, log=Log.NONE),
         )
 
     def _get_property(self, service_name: str, prop: str) -> str:
@@ -240,11 +240,15 @@ class SystemdUserService:
         service_name = self._service_name(name)
 
         result = self._systemctl("stop", service_name)
-        if result.returncode != 0 and "not loaded" not in result.stderr.lower():
+        if (
+            result.returncode != 0
+            and "not loaded" not in result.stderr.lower()
+            and "does not exist" not in result.stderr.lower()
+        ):
             msg = f"Failed to stop service: {result.stderr}"
             raise ClanError(msg)
 
-        self._systemctl("disable", service_name)  # Ignore errors for transient units
+        result = self._systemctl("disable", service_name)
 
         unit_file = self._unit_file_path(name)
         if unit_file.exists():

pkgs/classgen/main.py

@@ -241,6 +241,11 @@ def generate_dataclass(
         # If we are at the top level, and the attribute name is not explicitly included we only do shallow
         field_name = prop.replace("-", "_")
 
+        # Skip "extraModules"
+        # TODO: Introduce seperate model that is tied to the serialization format
+        if "extraModules" in field_name:
+            continue
+
         # if len(attr_path) == 0 and prop in shallow_attrs:
         #     field_def = field_name, "dict[str, Any]"
         #     fields_with_default.append(field_def)

pkgs/docs-from-code/flake-module.nix

@@ -64,6 +64,9 @@
           '';
     in
     {
+      legacyPackages = {
+        inherit jsonDocs clanModulesViaService;
+      };
       packages = {
         inherit module-docs;
       };

pkgs/option-search/flake-module.nix

@@ -11,151 +11,10 @@
       ...
     }:
     let
-      inherit (lib)
-        mapAttrsToList
-        mapAttrs
-        mkOption
-        types
-        splitString
-        stringLength
-        substring
-        ;
-      inherit (self) clanLib;
-
-      serviceModules = self.clan.modules;
 
       baseHref = "/option-search/";
 
-      getRoles =
-        module:
-        (clanLib.evalService {
-          modules = [ module ];
-          prefix = [ ];
-        }).config.roles;
-
-      getManifest =
-        module:
-        (clanLib.evalService {
-          modules = [ module ];
-          prefix = [ ];
-        }).config.manifest;
-
-      settingsModules = module: mapAttrs (_roleName: roleConfig: roleConfig.interface) (getRoles module);
-
       # Map each letter to its capitalized version
-      capitalizeChar =
-        char:
-        {
-          a = "A";
-          b = "B";
-          c = "C";
-          d = "D";
-          e = "E";
-          f = "F";
-          g = "G";
-          h = "H";
-          i = "I";
-          j = "J";
-          k = "K";
-          l = "L";
-          m = "M";
-          n = "N";
-          o = "O";
-          p = "P";
-          q = "Q";
-          r = "R";
-          s = "S";
-          t = "T";
-          u = "U";
-          v = "V";
-          w = "W";
-          x = "X";
-          y = "Y";
-          z = "Z";
-        }
-        .${char};
-
-      title =
-        name:
-        let
-          # split by -
-          parts = splitString "-" name;
-          # capitalize first letter of each part
-          capitalize = part: (capitalizeChar (substring 0 1 part)) + substring 1 (stringLength part) part;
-          capitalizedParts = map capitalize parts;
-        in
-        builtins.concatStringsSep " " capitalizedParts;
-
-      fakeInstanceOptions =
-        name: module:
-        let
-          manifest = getManifest module;
-          description = ''
-            # ${title name} (Clan Service)
-
-            **${manifest.description}**
-
-            ${lib.optionalString (manifest ? readme) manifest.readme}
-
-            ${
-              if manifest.categories != [ ] then
-                "Categories: " + builtins.concatStringsSep ", " manifest.categories
-              else
-                "No categories defined"
-            }
-
-          '';
-        in
-        {
-          options = {
-            instances.${name} = lib.mkOption {
-              inherit description;
-              type = types.submodule {
-                options.roles = mapAttrs (
-                  roleName: roleSettingsModule:
-                  mkOption {
-                    type = types.submodule {
-                      _file = "docs flake-module";
-                      imports = [
-                        { _module.args = { inherit clanLib; }; }
-                        (import ../../modules/inventoryClass/role.nix {
-                          nestedSettingsOption = mkOption {
-                            type = types.raw;
-                            description = ''
-                              See [instances.${name}.roles.${roleName}.settings](${baseHref}?option_scope=0&option=inventory.instances.${name}.roles.${roleName}.settings)
-                            '';
-                          };
-                          settingsOption = mkOption {
-                            type = types.submoduleWith {
-                              modules = [ roleSettingsModule ];
-                            };
-                          };
-                        })
-                      ];
-                    };
-                  }
-                ) (settingsModules module);
-              };
-            };
-          };
-        };
-
-      docModules = [
-        {
-          inherit self;
-        }
-        self.modules.clan.default
-        {
-          options.inventory = lib.mkOption {
-            type = types.submoduleWith {
-              modules = [
-                { noInstanceOptions = true; }
-              ]
-              ++ mapAttrsToList fakeInstanceOptions serviceModules;
-            };
-          };
-        }
-      ];
 
       baseModule =
         # Module
@@ -208,12 +67,6 @@
               title = "Clan Options";
               # scopes = mapAttrsToList mkScope serviceModules;
               scopes = [
-                {
-                  inherit baseHref;
-                  name = "Flake Options (clan.nix file)";
-                  modules = docModules;
-                  urlPrefix = "https://git.clan.lol/clan/clan-core/src/branch/main/";
-                }
                 {
                   name = "Machine Options (clan.core NixOS options)";
                   optionsJSON = "${coreOptions}/share/doc/nixos/options.json";