Add prometheus role to monitoring

.gitea/workflows/checks.yaml

@@ -0,0 +1,9 @@
+name: checks
+on:
+  pull_request:
+jobs:
+  checks-impure:
+    runs-on: nix
+    steps:
+      - uses: actions/checkout@v4
+      - run: nix run .#impure-checks

.gitignore

@@ -39,6 +39,7 @@ select
 # Generated files
 pkgs/clan-app/ui/api/API.json
 pkgs/clan-app/ui/api/API.ts
+pkgs/clan-app/ui/api/Inventory.ts
 pkgs/clan-app/ui/api/modules_schemas.json
 pkgs/clan-app/ui/api/schema.json
 pkgs/clan-app/ui/.fonts

CODEOWNERS

@@ -1,20 +0,0 @@
-clanServices/.* @pinpox @kenji
-
-lib/test/container-test-driver/.* @DavHau @mic92
-lib/modules/inventory/.* @hsjobeki
-lib/modules/inventoryClass/.* @hsjobeki
-
-pkgs/clan-app/ui/.* @hsjobeki @brianmcgee
-pkgs/clan-app/clan_app/.* @qubasa @hsjobeki
-
-pkgs/clan-cli/clan_cli/.* @lassulus @mic92 @kenji
-pkgs/clan-cli/clan_cli/(secrets|vars)/.* @DavHau @lassulus
-
-pkgs/clan-cli/clan_lib/log_machines/.* @Qubasa
-pkgs/clan-cli/clan_lib/ssh/.* @Qubasa @Mic92 @lassulus
-pkgs/clan-cli/clan_lib/tags/.* @hsjobeki
-pkgs/clan-cli/clan_lib/persist/.* @hsjobeki
-pkgs/clan-cli/clan_lib/flake/.* @lassulus
-
-pkgs/clan-cli/api.py @hsjobeki
-pkgs/clan-cli/openapi.py @hsjobeki

CONTRIBUTING.md

@@ -1,6 +1,4 @@
 # Contributing to Clan
 
 <!-- Local file: docs/CONTRIBUTING.md -->
-
-Go to the Contributing guide at
-https://docs.clan.lol/guides/contributing/CONTRIBUTING
+Go to the Contributing guide at https://docs.clan.lol/guides/contributing/CONTRIBUTING

LICENSE.md

@@ -16,3 +16,4 @@ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

README.md

@@ -1,69 +1,45 @@
 # Clan core repository
 
-Welcome to the Clan core repository, the heart of the
-[clan.lol](https://clan.lol/) project! This monorepo is the foundation of Clan,
-a revolutionary open-source project aimed at restoring fun, freedom, and
-functionality to computing. Here, you'll find all the essential packages, NixOS
-modules, CLI tools, and tests needed to contribute to and work with the Clan
-project. Clan leverages the Nix system to ensure reliability, security, and
-seamless management of digital environments, putting the power back into the
-hands of users.
+Welcome to the Clan core repository, the heart of the [clan.lol](https://clan.lol/) project! This monorepo is the foundation of Clan, a revolutionary open-source project aimed at restoring fun, freedom, and functionality to computing. Here, you'll find all the essential packages, NixOS modules, CLI tools, and tests needed to contribute to and work with the Clan project. Clan leverages the Nix system to ensure reliability, security, and seamless management of digital environments, putting the power back into the hands of users.
 
 ## Why Clan?
 
-Our mission is simple: to democratize computing by providing tools that empower
-users, foster innovation, and challenge outdated paradigms. Clan represents our
-contribution to a future where technology serves humanity, not the other way
-around. By participating in Clan, you're joining a movement dedicated to
-creating a secure, user-empowered digital future.
+Our mission is simple: to democratize computing by providing tools that empower users, foster innovation, and challenge outdated paradigms. Clan represents our contribution to a future where technology serves humanity, not the other way around. By participating in Clan, you're joining a movement dedicated to creating a secure, user-empowered digital future.
 
 ## Features of Clan
 
-- **Full-Stack System Deployment:** Utilize Clan's toolkit alongside Nix's
-  reliability to build and manage systems effortlessly.
+- **Full-Stack System Deployment:** Utilize Clan’s toolkit alongside Nix's reliability to build and manage systems effortlessly.
 - **Overlay Networks:** Secure, private communication channels between devices.
-- **Virtual Machine Integration:** Seamless operation of VM applications within
-  the main operating system.
+- **Virtual Machine Integration:** Seamless operation of VM applications within the main operating system.
 - **Robust Backup Management:** Long-term, self-hosted data preservation.
-- **Intuitive Secret Management:** Simplified encryption and password management
-  processes.
+- **Intuitive Secret Management:** Simplified encryption and password management processes.
 
 ## Getting started with Clan
 
-If you're new to Clan and eager to dive in, start with our quickstart guide and
-explore the core functionalities that Clan offers:
+If you're new to Clan and eager to dive in, start with our quickstart guide and explore the core functionalities that Clan offers:
 
-- **Quickstart Guide**: Check out
-  [getting started](https://docs.clan.lol/#starting-with-a-new-clan-project)<!-- [docs/site/index.md](docs/site/index.md) -->
-  to get up and running with Clan in no time.
+- **Quickstart Guide**: Check out [getting started](https://docs.clan.lol/#starting-with-a-new-clan-project)<!-- [docs/site/index.md](docs/site/index.md) --> to get up and running with Clan in no time.
 
 ### Managing secrets
 
-In the Clan ecosystem, security is paramount. Learn how to handle secrets
-effectively:
+In the Clan ecosystem, security is paramount. Learn how to handle secrets effectively:
 
-- **Secrets Management**: Securely manage secrets by consulting
-  [Vars](https://docs.clan.lol/concepts/generators/)<!-- [secrets.md](docs/site/concepts/generators.md) -->.
+- **Secrets Management**: Securely manage secrets by consulting [Vars](https://docs.clan.lol/concepts/generators/)<!-- [secrets.md](docs/site/concepts/generators.md) -->.
 
 ### Contributing to Clan
 
-The Clan project thrives on community contributions. We welcome everyone to
-contribute and collaborate:
+The Clan project thrives on community contributions. We welcome everyone to contribute and collaborate:
 
-- **Contribution Guidelines**: Make a meaningful impact by following the steps
-  in
-  [contributing](https://docs.clan.lol/contributing/contributing/)<!-- [contributing.md](docs/CONTRIBUTING.md) -->.
+- **Contribution Guidelines**: Make a meaningful impact by following the steps in [contributing](https://docs.clan.lol/contributing/contributing/)<!-- [contributing.md](docs/CONTRIBUTING.md) -->.
 
 ## Join the revolution
 
-Clan is more than a tool; it's a movement towards a better digital future. By
-contributing to the Clan project, you're part of changing technology for the
-better, together.
+Clan is more than a tool; it's a movement towards a better digital future. By contributing to the Clan project, you're part of changing technology for the better, together.
 
 ### Community and support
 
 Connect with us and the Clan community for support and discussion:
 
 - [Matrix channel](https://matrix.to/#/#clan:clan.lol) for live discussions.
-- IRC bridge on [hackint#clan](https://chat.hackint.org/#/connect?join=clan) for
-  real-time chat support.
+- IRC bridge on [hackint#clan](https://chat.hackint.org/#/connect?join=clan) for real-time chat support.
+

checks/flake-module.nix

@@ -36,6 +36,7 @@ in
     ++ filter pathExists [
       ./devshell/flake-module.nix
       ./flash/flake-module.nix
+      ./impure/flake-module.nix
       ./installation/flake-module.nix
       ./update/flake-module.nix
       ./morph/flake-module.nix
@@ -138,6 +139,33 @@ in
         nixosTests
         // flakeOutputs
         // {
+          # TODO: Automatically provide this check to downstream users to check their modules
+          clan-modules-json-compatible =
+            let
+              allSchemas = lib.mapAttrs (
+                _n: m:
+                let
+                  schema =
+                    (self.clanLib.evalService {
+                      modules = [ m ];
+                      prefix = [
+                        "checks"
+                        system
+                      ];
+                    }).config.result.api.schema;
+                in
+                schema
+              ) self.clan.modules;
+            in
+            pkgs.runCommand "combined-result"
+              {
+                schemaFile = builtins.toFile "schemas.json" (builtins.toJSON allSchemas);
+              }
+              ''
+                mkdir -p $out
+                cat $schemaFile > $out/allSchemas.json
+              '';
+
           clan-core-for-checks = pkgs.runCommand "clan-core-for-checks" { } ''
             cp -r ${privateInputs.clan-core-for-checks} $out
             chmod -R +w $out

checks/flash/flake-module.nix

@@ -55,8 +55,7 @@
       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 = pkgs.lib.mkIf pkgs.stdenv.isLinux {
         nixos-test-flash = self.clanLib.test.baseTest {
           name = "flash";
           nodes.target = {

checks/impure/flake-module.nix

@@ -0,0 +1,51 @@
+{
+  perSystem =
+    {
+      pkgs,
+      lib,
+      self',
+      ...
+    }:
+    {
+      # a script that executes all other checks
+      packages.impure-checks = pkgs.writeShellScriptBin "impure-checks" ''
+        #!${pkgs.bash}/bin/bash
+        set -euo pipefail
+
+        unset CLAN_DIR
+
+        export PATH="${
+          lib.makeBinPath (
+            [
+              pkgs.gitMinimal
+              pkgs.nix
+              pkgs.coreutils
+              pkgs.rsync # needed to have rsync installed on the dummy ssh server
+            ]
+            ++ self'.packages.clan-cli-full.runtimeDependencies
+          )
+        }"
+        ROOT=$(git rev-parse --show-toplevel)
+        cd "$ROOT/pkgs/clan-cli"
+
+        # Set up custom git configuration for tests
+        export GIT_CONFIG_GLOBAL=$(mktemp)
+        git config --file "$GIT_CONFIG_GLOBAL" user.name "Test User"
+        git config --file "$GIT_CONFIG_GLOBAL" user.email "test@example.com"
+        export GIT_CONFIG_SYSTEM=/dev/null
+
+        # this disables dynamic dependency loading in clan-cli
+        export CLAN_NO_DYNAMIC_DEPS=1
+
+        jobs=$(nproc)
+        # Spawning worker in pytest is relatively slow, so we limit the number of jobs to 13
+        # (current number of impure tests)
+        jobs="$((jobs > 13 ? 13 : jobs))"
+
+        nix develop "$ROOT#clan-cli" -c bash -c "TMPDIR=/tmp python -m pytest -n $jobs -m impure ./clan_cli $@"
+
+        # Clean up temporary git config
+        rm -f "$GIT_CONFIG_GLOBAL"
+      '';
+    };
+}

checks/installation/flake-module.nix

@@ -232,7 +232,6 @@
                       "-i", ssh_conn.ssh_key,
                       "--option", "store", os.environ['CLAN_TEST_STORE'],
                       "--update-hardware-config", "nixos-facter",
-                      "--no-persist-state",
                   ]
 
                   subprocess.run(clan_cmd, check=True)
@@ -242,7 +241,7 @@
                   target.shutdown()
               except BrokenPipeError:
                   # qemu has already exited
-                  target.connected = False
+                  pass
 
               # Create a new machine instance that boots from the installed system
               installed_machine = create_test_machine(target, "${pkgs.qemu_test}", name="after_install")
@@ -276,7 +275,7 @@
                       "${self.checks.x86_64-linux.clan-core-for-checks}",
                       "${closureInfo}"
                   )
-
+                  
                   # Set up SSH connection
                   ssh_conn = setup_ssh_connection(
                       target,

checks/service-dummy-test/legacy-module/README.md

@@ -1,6 +1,10 @@
-______________________________________________________________________
+---
+description = "Set up dummy-module"
+categories = ["System"]
+features = [ "inventory" ]
 
-description = "Set up dummy-module" categories = ["System"] features = \[
-"inventory" \]
+[constraints]
+roles.admin.min = 1
+roles.admin.max = 1
+---
 
-## [constraints] roles.admin.min = 1 roles.admin.max = 1

clanServices/dyndns/README.md

@@ -1,18 +1,15 @@
-A Dynamic-DNS (DDNS) service continuously keeps one or more DNS records in sync
-with the current public IP address of your machine.\
-In *clan* this service is backed by
-[qdm12/ddns-updater](https://github.com/qdm12/ddns-updater).
 
-> Info\
-> ddns-updater itself is **heavily opinionated and version-specific**. Whenever
-> you need the exhaustive list of flags or provider-specific fields refer to its
-> *versioned* documentation – **not** the GitHub README
+A Dynamic-DNS (DDNS) service continuously keeps one or more DNS records in sync with the current public IP address of your machine.  
+In *clan* this service is backed by [qdm12/ddns-updater](https://github.com/qdm12/ddns-updater).
 
-______________________________________________________________________
+> Info  
+> ddns-updater itself is **heavily opinionated and version-specific**. Whenever you need the exhaustive list of flags or
+> provider-specific fields refer to its *versioned* documentation – **not** the GitHub README
+---
 
 # 1. Configuration model
 
-Internally ddns-updater consumes a single file named `config.json`.\
+Internally ddns-updater consumes a single file named `config.json`.  
 A minimal configuration for the registrar *Namecheap* looks like:
 
 ```json
@@ -44,17 +41,16 @@ Another example for *Porkbun*:
 }
 ```
 
-When you write a `clan.nix` the **common** fields (`provider`, `domain`,
-`period`, …) are already exposed as typed *Nix options*.\
-Registrar-specific or very new keys can be passed through an open attribute set
-called **extraSettings**.
+When you write a `clan.nix` the **common** fields (`provider`, `domain`, `period`, …) are already exposed as typed
+*Nix options*.  
+Registrar-specific or very new keys can be passed through an open attribute set called **extraSettings**.
 
-______________________________________________________________________
+---
 
 # 2. Full Porkbun example
 
-Manage three records – `@`, `home` and `test` – of the domain `jon.blog` and
-refresh them every 15 minutes:
+Manage three records – `@`, `home` and `test` – of the domain
+`jon.blog` and refresh them every 15 minutes:
 
 ```nix title="clan.nix" hl_lines="10-11"
 inventory.instances = {
@@ -84,8 +80,7 @@ inventory.instances = {
 };
 ```
 
-1. `secret_field_name` tells the *vars-generator* to store the entered secret
-   under the specified JSON field name in the configuration.
+1. `secret_field_name` tells the *vars-generator* to store the entered secret under the specified JSON field name in the configuration.
 2. ddns-updater allows multiple hosts by separating them with a comma.
-3. The `api_key` above is *public*; the corresponding **private key** is
-   retrieved through `secret_field_name`.
+3. The `api_key` above is *public*; the corresponding **private key** is retrieved through `secret_field_name`.
+

clanServices/emergency-access/README.md

@@ -1,5 +1,4 @@
-This service will automatically set the emergency access password if your system
-fails to boot.
+This service will automatically set the emergency access password if your system fails to boot.
 
 ## Usage
 

clanServices/importer/README.md

@@ -1,6 +1,5 @@
-The importer module allows users to configure importing modules in a flexible
-and structured way. It exposes the `extraModules` functionality of the
-inventory, without any added configuration.
+The importer module allows users to configure importing modules in a flexible and structured way.
+It exposes the `extraModules` functionality of the inventory, without any added configuration.
 
 ## Usage
 
@@ -22,6 +21,6 @@ inventory.instances = {
 };
 ```
 
-This will import the module `modules/base.nix` to all machines that have the
-`all` tag, which by default is every machine managed by the clan. And also
-import for all machines tagged with `zone1` the module at `modules/zone1.nix`.
+This will import the module `modules/base.nix` to all machines that have the `all` tag,
+which by default is every machine managed by the clan.
+And also import for all machines tagged with `zone1` the module at `modules/zone1.nix`.

clanServices/localbackup/README.md

@@ -32,5 +32,4 @@ The service provides these commands:
 
 - `localbackup-create`: Create a new backup
 - `localbackup-list`: List available backups
-- `localbackup-restore`: Restore from backup (requires NAME and FOLDERS
-  environment variables)
+- `localbackup-restore`: Restore from backup (requires NAME and FOLDERS environment variables)

clanServices/monitoring/README.md

@@ -14,3 +14,4 @@ inventory.instances = {
 This service will eventually set up a monitoring stack for your clan. For now,
 only a telegraf role is implemented, which exposes the currently deployed
 version of your configuration, so it can be used to check for required updates.
+

clanServices/monitoring/default.nix

@@ -24,5 +24,12 @@
       };
   };
 
-  imports = [ ./telegraf.nix ];
+  # roles.prometheus = {
+  #   interface = { lib, ... }: { };
+  # };
+
+  imports = [
+    ./telegraf.nix
+    ./prometheus.nix
+  ];
 }

clanServices/monitoring/prometheus.nix

@@ -0,0 +1,182 @@
+{
+  roles.prometheus.perInstance =
+    { settings, roles, ... }:
+    {
+      nixosModule =
+        { pkgs, lib, ... }:
+        {
+
+          # imports = [
+          #   # ./matrix-alertmanager.nix
+          #   # ./irc-alertmanager.nix
+          #   # ./rules.nix
+          # ];
+
+          services.prometheus = {
+
+            # webExternalUrl = "https://prometheus.thalheim.io";
+            extraFlags = [ "--storage.tsdb.retention.time=30d" ];
+            scrapeConfigs = [
+              {
+                job_name = "telegraf";
+                scrape_interval = "60s";
+                metrics_path = "/metrics";
+                static_configs = [
+
+                  (map (host: {
+
+                    labels.host = host;
+                    # labels.org = "TODO";
+                    targets = [ "${host}.clan:9273" ];
+
+                  }) lib.attrNames roles.telegraf.machines)
+
+                  # {
+                  #   # labels.host = "rauter.r:9273";
+                  #   # labels.org = "TODO";
+                  #   targets = map (host: "${host}.clan:9273") lib.attrNames roles.telegraf.machines;
+                  # }
+                ];
+              }
+              # {
+              #   job_name = "gitea";
+              #   scrape_interval = "60s";
+              #   metrics_path = "/metrics";
+              #
+              #   scheme = "https";
+              #   static_configs = [ { targets = [ "git.thalheim.io:443" ]; } ];
+              # }
+            ];
+            alertmanagers = [ { static_configs = [ { targets = [ "localhost:9093" ]; } ]; } ];
+          };
+          services.prometheus.alertmanager = {
+            enable = true;
+            # environmentFile = config.sops.secrets.alertmanager.path;
+            # webExternalUrl = "https://alertmanager.thalheim.io";
+            # listenAddress = "[::1]";
+            # configuration = {
+            #   global = {
+            #     # The smarthost and SMTP sender used for mail notifications.
+            #     smtp_smarthost = "mail.thalheim.io:587";
+            #     smtp_from = "alertmanager@thalheim.io";
+            #     smtp_auth_username = "alertmanager@thalheim.io";
+            #     smtp_auth_password = "$SMTP_PASSWORD";
+            #   };
+            #   route = {
+            #     receiver = "default";
+            #     routes = [
+            #       {
+            #         group_by = [ "host" ];
+            #         match_re.org = "krebs";
+            #         group_wait = "5m";
+            #         group_interval = "5m";
+            #         repeat_interval = "4h";
+            #         receiver = "krebs";
+            #       }
+            #       {
+            #         group_by = [ "host" ];
+            #         match_re.org = "nixos-wiki";
+            #         group_wait = "5m";
+            #         group_interval = "5m";
+            #         repeat_interval = "4h";
+            #         receiver = "nixos-wiki";
+            #       }
+            #       {
+            #         group_by = [ "host" ];
+            #         match_re.org = "numtide";
+            #         group_wait = "5m";
+            #         group_interval = "5m";
+            #         repeat_interval = "4h";
+            #         receiver = "numtide";
+            #       }
+            #       {
+            #         group_by = [ "host" ];
+            #         match_re.org = "clan-lol";
+            #         group_wait = "5m";
+            #         group_interval = "5m";
+            #         repeat_interval = "4h";
+            #         receiver = "clan-lol";
+            #       }
+            #       {
+            #         group_by = [ "host" ];
+            #         match_re.org = "dave";
+            #         group_wait = "5m";
+            #         group_interval = "5m";
+            #         repeat_interval = "4h";
+            #         receiver = "dave";
+            #       }
+            #       {
+            #         group_by = [ "host" ];
+            #         group_wait = "30s";
+            #         group_interval = "2m";
+            #         repeat_interval = "2h";
+            #         receiver = "all";
+            #       }
+            #     ];
+            #   };
+            #   receivers = [
+            #     {
+            #       name = "krebs";
+            #       webhook_configs = [
+            #         {
+            #           url = "http://127.0.0.1:9223/";
+            #           max_alerts = 5;
+            #         }
+            #       ];
+            #     }
+            #     {
+            #       name = "numtide";
+            #       webhook_configs = [
+            #         # TODO
+            #         #{
+            #         #  send_resolved = true;
+            #         #  url = "https://chat.ntd.one/plugins/alertmanager/api/webhook?token='xxxxxxxxxxxxxxxxxxx-yyyyyyy'";
+            #         #}
+            #       ];
+            #     }
+            #     {
+            #       name = "nixos-wiki";
+            #       webhook_configs = [
+            #         {
+            #           url = "http://localhost:9088/alert";
+            #           max_alerts = 5;
+            #         }
+            #       ];
+            #     }
+            #     {
+            #       name = "clan-lol";
+            #       webhook_configs = [
+            #         # TODO
+            #         #{
+            #         #  url = "http://localhost:4050/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U";
+            #         #  max_alerts = 5;
+            #         #}
+            #       ];
+            #     }
+            #     {
+            #       name = "dave";
+            #       telegram_configs = [
+            #         {
+            #           chat_id = 42927997;
+            #           bot_token = "$TELEGRAM_BOT_TOKEN";
+            #         }
+            #       ];
+            #     }
+            #     {
+            #       name = "all";
+            #       # pushover_configs = [
+            #       #   {
+            #       #     user_key = "$PUSHOVER_USER_KEY";
+            #       #     token = "$PUSHOVER_TOKEN";
+            #       #     priority = "0";
+            #       #   }
+            #       # ];
+            #     }
+            #     { name = "default"; }
+            #   ];
+            # };
+          };
+
+        };
+    };
+}

clanServices/monitoring/telegraf.nix

@@ -4,66 +4,22 @@
     {
 
       nixosModule =
-        {
-          config,
-          pkgs,
-          lib,
-          ...
-        }:
-        let
-          jsonpath = "/tmp/telegraf.json";
-          auth_user = "prometheus";
-        in
+        { pkgs, lib, ... }:
         {
 
           networking.firewall.interfaces = lib.mkIf (settings.allowAllInterfaces == false) (
             builtins.listToAttrs (
               map (name: {
                 inherit name;
-                value.allowedTCPPorts = [
-                  9273
-                  9990
-                ];
+                value.allowedTCPPorts = [ 9273 ];
               }) settings.interfaces
             )
           );
 
-          networking.firewall.allowedTCPPorts = lib.mkIf (settings.allowAllInterfaces == true) [
-            9273
-            9990
-          ];
-
-          clan.core.vars.generators."telegraf" = {
-
-            files.password.restartUnits = [ "telegraf.service" ];
-            files.password-env.restartUnits = [ "telegraf.service" ];
-            files.miniserve-auth.restartUnits = [ "telegraf.service" ];
-
-            runtimeInputs = [
-              pkgs.coreutils
-              pkgs.xkcdpass
-              pkgs.mkpasswd
-            ];
-
-            script = ''
-              PASSWORD=$(xkcdpass --numwords 4 --delimiter - --count 1 | tr -d "\n")
-              echo "BASIC_AUTH_PWD=$PASSWORD" > "$out"/password-env
-              echo "${auth_user}:$PASSWORD" > "$out"/miniserve-auth
-              echo "$PASSWORD" | tr -d "\n" > "$out"/password
-            '';
-          };
-
-          systemd.services.telegraf-json = {
-            enable = true;
-            wantedBy = [ "multi-user.target" ];
-            script = "${pkgs.miniserve}/bin/miniserve -p 9990 ${jsonpath} --auth-file ${config.clan.core.vars.generators.telegraf.files.miniserve-auth.path}";
-          };
+          networking.firewall.allowedTCPPorts = lib.mkIf (settings.allowAllInterfaces == true) [ 9273 ];
 
           services.telegraf = {
             enable = true;
-            environmentFiles = [
-              (builtins.toString config.clan.core.vars.generators.telegraf.files.password-env.path)
-            ];
             extraConfig = {
               agent.interval = "60s";
               inputs = {
@@ -77,34 +33,22 @@
 
                 exec =
                   let
-                    nixosSystems = pkgs.writeShellScript "current-system" ''
-                      printf "nixos_systems,current_system=%s,booted_system=%s,current_kernel=%s,booted_kernel=%s present=0\n" \
-                        "$(readlink /run/current-system)" "$(readlink /run/booted-system)" \
-                        "$(basename $(echo /run/current-system/kernel-modules/lib/modules/*))" \
-                        "$(basename $(echo /run/booted-system/kernel-modules/lib/modules/*))"
+                    currentSystemScript = pkgs.writeShellScript "current-system" ''
+                      printf "current_system,path=%s present=0\n" $(readlink /run/current-system)
                     '';
                   in
                   [
                     {
                       # Expose the path to current-system as metric. We use
                       # this to check if the machine is up-to-date.
-                      commands = [ nixosSystems ];
+                      commands = [ currentSystemScript ];
                       data_format = "influx";
                     }
                   ];
               };
-              # sadly there doesn'T seem to exist a telegraf http_client output plugin
               outputs.prometheus_client = {
                 listen = ":9273";
                 metric_version = 2;
-                basic_username = "${auth_user}";
-                basic_password = "$${BASIC_AUTH_PWD}";
-              };
-
-              outputs.file = {
-                files = [ jsonpath ];
-                data_format = "json";
-                json_timestamp_units = "1s";
               };
             };
           };

clanServices/sshd/README.md

@@ -1,13 +1,8 @@
-The `sshd` Clan service manages SSH to make it easy to securely access your
-machines over the internet. The service uses `vars` to store the SSH host keys
-for each machine to ensure they remain stable across deployments.
+The `sshd` Clan service manages SSH to make it easy to securely access your machines over the internet. The service uses `vars` to store the SSH host keys for each machine to ensure they remain stable across deployments.
 
-`sshd` also generates SSH certificates for both servers and clients allowing for
-certificate-based authentication for SSH.
+`sshd` also generates SSH certificates for both servers and clients allowing for certificate-based authentication for SSH.
 
-The service also disables password-based authentication over SSH, to access your
-machines you'll need to use public key authentication or certificate-based
-authentication.
+The service also disables password-based authentication over SSH, to access your machines you'll need to use public key authentication or certificate-based authentication.
 
 ## Usage
 

clanServices/syncthing/README.md

@@ -15,7 +15,6 @@
 
 Now the folder `~/syncthing/documents` will be shared with all your machines.
 
-## Documentation
 
-Extensive documentation is available on the
-[Syncthing](https://docs.syncthing.net/) website.
+## Documentation 
+Extensive documentation is available on the [Syncthing](https://docs.syncthing.net/) website.

clanServices/users/README.md

@@ -17,20 +17,6 @@
       };
     };
 
-    # Deploy user Carol on all machines. Prompt only once and use the
-    # same password on all machines. (`share = true`)
-    user-carol = {
-      module = {
-        name = "users";
-        input = "clan";
-      };
-      roles.default.tags.all = { };
-      roles.default.settings = {
-        user = "carol";
-        share = true;
-      };
-    };
-
     # Deploy user bob only on his laptop. Prompt for a password.
     user-bob = {
       module = {
@@ -43,45 +29,3 @@
   };
 }
 ```
-
-## Migration from `root-password` module
-
-The deprecated `clan.root-password` module has been replaced by the `users`
-module. Here's how to migrate:
-
-### 1. Update your flake configuration
-
-Replace the `root-password` module import with a `users` service instance:
-
-```nix
-# OLD - Remove this from your nixosModules:
-imports = [
-  self.inputs.clan-core.clanModules.root-password
-];
-
-# NEW - Add to inventory.instances or machines/flake-module.nix:
-instances = {
-  users-root = {
-    module.name = "users";
-    module.input = "clan-core";
-    roles.default.tags.nixos = { };
-    roles.default.settings = {
-      user = "root";
-      prompt = false;  # Set to true if you want to be prompted
-      groups = [ ];
-    };
-  };
-};
-```
-
-### 2. Migrate vars
-
-The vars structure has changed from `root-password` to `user-password-root`:
-
-```bash
-# For each machine, rename the vars directories:
-cd vars/per-machine/<machine-name>/
-mv root-password user-password-root
-mv user-password-root/password-hash user-password-root/user-password-hash
-mv user-password-root/password user-password-root/user-password
-```

clanServices/users/default.nix

@@ -59,17 +59,6 @@
               - "input" - Allows the user to access input devices.
             '';
           };
-          share = lib.mkOption {
-            type = lib.types.bool;
-            default = false;
-            example = true;
-            description = ''
-              Weather the user should have the same password on all machines.
-
-              By default, you will be prompted for a new password for every host.
-              Unless `generate` is set to `true`.
-            '';
-          };
         };
       };
 
@@ -93,6 +82,7 @@
             };
 
             clan.core.vars.generators."user-password-${settings.user}" = {
+
               files.user-password-hash.neededFor = "users";
               files.user-password-hash.restartUnits = lib.optional (config.services.userborn.enable) "userborn.service";
               files.user-password.deploy = false;
@@ -117,8 +107,6 @@
                 pkgs.mkpasswd
               ];
 
-              share = settings.share;
-
               script =
                 (
                   if settings.prompt then

clanServices/wireguard/README.md

@@ -1,23 +1,17 @@
 # Wireguard VPN Service
 
-This service provides a Wireguard-based VPN mesh network with automatic IPv6
-address allocation and routing between clan machines.
+This service provides a Wireguard-based VPN mesh network with automatic IPv6 address allocation and routing between clan machines.
 
 ## Overview
 
-The wireguard service creates a secure mesh network between clan machines using
-two roles:
-
-- **Controllers**: Machines with public endpoints that act as connection points
-  and routers
+The wireguard service creates a secure mesh network between clan machines using two roles:
+- **Controllers**: Machines with public endpoints that act as connection points and routers
 - **Peers**: Machines that connect through controllers to access the network
 
 ## Requirements
 
-- Controllers must have a publicly accessible endpoint (domain name or static
-  IP)
-- Peers must be in networks where UDP traffic is not blocked (uses port 51820 by
-  default, configurable)
+- Controllers must have a publicly accessible endpoint (domain name or static IP)
+- Peers must be in networks where UDP traffic is not blocked (uses port 51820 by default, configurable)
 
 ## Features
 
@@ -30,33 +24,24 @@ two roles:
 ## Network Architecture
 
 ### IPv6 Address Allocation
-
-- Base network: `/40` ULA prefix (deterministically generated from instance
-  name)
+- Base network: `/40` ULA prefix (deterministically generated from instance name)
 - Controllers: Each gets a `/56` subnet from the base `/40`
-- Peers: Each gets a unique 64-bit host suffix that is used in ALL controller
-  subnets
+- Peers: Each gets a unique 64-bit host suffix that is used in ALL controller subnets
 
 ### Addressing Design
-
 - Each peer generates a unique host suffix (e.g., `:8750:a09b:0:1`)
-- This suffix is appended to each controller's `/56` prefix to create unique
-  addresses
+- This suffix is appended to each controller's `/56` prefix to create unique addresses
 - Example: peer1 with suffix `:8750:a09b:0:1` gets:
   - `fd51:19c1:3b:f700:8750:a09b:0:1` in controller1's subnet
   - `fd51:19c1:c1:aa00:8750:a09b:0:1` in controller2's subnet
 - Controllers allow each peer's `/96` subnet for routing flexibility
 
 ### Connectivity
-
-- Peers use a single WireGuard interface with multiple IPs (one per controller
-  subnet)
-- Controllers connect to ALL other controllers and ALL peers on a single
-  interface
+- Peers use a single WireGuard interface with multiple IPs (one per controller subnet)
+- Controllers connect to ALL other controllers and ALL peers on a single interface
 - Controllers have IPv6 forwarding enabled to route traffic between peers
 - All traffic between peers flows through controllers
-- Symmetric routing is maintained as each peer has consistent IPs across all
-  controllers
+- Symmetric routing is maintained as each peer has consistent IPs across all controllers
 
 ### Example Network Topology
 
@@ -146,14 +131,12 @@ graph TB
 
 ### Advanced Options
 
+
 ### Automatic Hostname Resolution
 
-The wireguard service automatically adds entries to `/etc/hosts` for all
-machines in the network. Each machine is accessible via its hostname in the
-format `<machine-name>.<instance-name>`.
+The wireguard service automatically adds entries to `/etc/hosts` for all machines in the network. Each machine is accessible via its hostname in the format `<machine-name>.<instance-name>`.
 
 For example, with an instance named `vpn`:
-
 - `server1.vpn` - resolves to server1's IPv6 address
 - `laptop1.vpn` - resolves to laptop1's IPv6 address
 
@@ -170,19 +153,16 @@ ssh user@laptop1.vpn
 ## Troubleshooting
 
 ### Check Wireguard Status
-
 ```bash
 sudo wg show
 ```
 
 ### Verify IP Addresses
-
 ```bash
 ip addr show dev <instance-name>
 ```
 
 ### Check Routing
-
 ```bash
 ip -6 route show dev <instance-name>
 ```
@@ -190,23 +170,19 @@ ip -6 route show dev <instance-name>
 ### Interface Fails to Start: "Address already in use"
 
 If you see this error in your logs:
-
 ```
 wireguard: Could not bring up interface, ignoring: Address already in use
 ```
 
-This means the configured port (default: 51820) is already in use by another
-service or wireguard instance. Solutions:
+This means the configured port (default: 51820) is already in use by another service or wireguard instance. Solutions:
 
 1. **Check for conflicting wireguard instances:**
-
    ```bash
    sudo wg show
    sudo ss -ulnp | grep 51820
    ```
 
 2. **Use a different port:**
-
    ```nix
    services.wireguard.myinstance = {
      roles.controller = {
@@ -216,13 +192,12 @@ service or wireguard instance. Solutions:
    };
    ```
 
-3. **Ensure unique ports across multiple instances:** If you have multiple
-   wireguard instances on the same machine, each must use a different port.
+3. **Ensure unique ports across multiple instances:**
+   If you have multiple wireguard instances on the same machine, each must use a different port.
 
 ### Key Management
 
-Keys are automatically generated and stored in the clan vars system. To
-regenerate keys:
+Keys are automatically generated and stored in the clan vars system. To regenerate keys:
 
 ```bash
 # Regenerate keys for a specific machine and instance
@@ -239,3 +214,4 @@ clan machines update <machine-name>
 - Public keys are distributed through the clan vars system
 - Controllers must have publicly accessible endpoints
 - Firewall rules are automatically configured for the Wireguard ports
+

clanServices/wireguard/ipv6_allocator.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
-"""IPv6 address allocator for WireGuard networks.
+"""
+IPv6 address allocator for WireGuard networks.
 
 Network layout:
 - Base network: /40 ULA prefix (fd00::/8 + 32 bits from hash)
@@ -19,7 +20,8 @@ def hash_string(s: str) -> str:
 
 
 def generate_ula_prefix(instance_name: str) -> ipaddress.IPv6Network:
-    """Generate a /40 ULA prefix from instance name.
+    """
+    Generate a /40 ULA prefix from instance name.
 
     Format: fd{32-bit hash}/40
     This gives us fd00:0000:0000::/40 through fdff:ffff:ff00::/40
@@ -44,10 +46,10 @@ def generate_ula_prefix(instance_name: str) -> ipaddress.IPv6Network:
 
 
 def generate_controller_subnet(
-    base_network: ipaddress.IPv6Network,
-    controller_name: str,
+    base_network: ipaddress.IPv6Network, controller_name: str
 ) -> ipaddress.IPv6Network:
-    """Generate a /56 subnet for a controller from the base /40 network.
+    """
+    Generate a /56 subnet for a controller from the base /40 network.
 
     We have 16 bits (40 to 56) to allocate controller subnets.
     This allows for 65,536 possible controller subnets.
@@ -66,7 +68,8 @@ def generate_controller_subnet(
 
 
 def generate_peer_suffix(peer_name: str) -> str:
-    """Generate a unique 64-bit host suffix for a peer.
+    """
+    Generate a unique 64-bit host suffix for a peer.
 
     This suffix will be used in all controller subnets to create unique addresses.
     Format: :xxxx:xxxx:xxxx:xxxx (64 bits)
@@ -83,7 +86,7 @@ def generate_peer_suffix(peer_name: str) -> str:
 def main() -> None:
     if len(sys.argv) < 4:
         print(
-            "Usage: ipv6_allocator.py <output_dir> <instance_name> <controller|peer> <machine_name>",
+            "Usage: ipv6_allocator.py <output_dir> <instance_name> <controller|peer> <machine_name>"
         )
         sys.exit(1)
 

clanServices/zerotier/README.md

@@ -13,37 +13,32 @@ inventory.instances = {
   };
 ```
 
-The input should be named according to your flake input. All machines will be
-peers and connected to the zerotier network. Jon is the controller machine,
-which will will accept other machines into the network. Sara is a moon and sets
-the `stableEndpoint` setting with a publicly reachable IP, the moon is optional.
+The input should be named according to your flake input.
+All machines will be peers and connected to the zerotier network.
+Jon is the controller machine, which will will accept other machines into the network.
+Sara is a moon and sets the `stableEndpoint` setting with a publicly reachable IP, the moon is optional.
+
 
 ## Overview
 
-This guide explains how to set up and manage a
-[ZeroTier VPN](https://zerotier.com) for a clan network. Each VPN requires a
-single controller and can support multiple peers and optional moons for better
-connectivity.
+This guide explains how to set up and manage a [ZeroTier VPN](https://zerotier.com) for a clan network. Each VPN requires a single controller and can support multiple peers and optional moons for better connectivity.
 
 ## Roles
 
 ### 1. Controller
 
-The [Controller](https://docs.zerotier.com/controller/) manages network
-membership and is responsible for admitting new peers. When a new node is added
-to the clan, the controller must be updated to ensure it has the latest member
-list.
+The [Controller](https://docs.zerotier.com/controller/) manages network membership and is responsible for admitting new peers.
+When a new node is added to the clan, the controller must be updated to ensure it has the latest member list.
 
 - **Key Points:**
   - Must be online to admit new machines to the VPN.
-  - Existing nodes can continue to communicate even when the controller is
-    offline.
+  - Existing nodes can continue to communicate even when the controller is offline.
 
 ### 2. Moons
 
-[Moons](https://docs.zerotier.com/roots) act as relay nodes, providing direct
-connectivity to peers via their public IP addresses. They enable devices that
-are not publicly reachable to join the VPN by routing through these nodes.
+[Moons](https://docs.zerotier.com/roots) act as relay nodes,
+providing direct connectivity to peers via their public IP addresses.
+They enable devices that are not publicly reachable to join the VPN by routing through these nodes.
 
 - **Configuration Notes:**
   - Each moon must define its public IP address.
@@ -51,8 +46,8 @@ are not publicly reachable to join the VPN by routing through these nodes.
 
 ### 3. Peers
 
-Peers are standard nodes in the VPN. They connect to other peers, moons, and the
-controller as needed.
+Peers are standard nodes in the VPN.
+They connect to other peers, moons, and the controller as needed.
 
 - **Purpose:**
   - General role for all machines that are neither controllers nor moons.

devFlake/flake.lock

@@ -3,10 +3,10 @@
     "clan-core-for-checks": {
       "flake": false,
       "locked": {
-        "lastModified": 1756133826,
-        "narHash": "sha256-In3u7UVSjPzX9u4Af9K/jVy4MMAZBzxByMe4GREpHBo=",
+        "lastModified": 1755093452,
+        "narHash": "sha256-NKBss7QtNnOqYVyJmYCgaCvYZK0mpQTQc9fLgE1mGyk=",
         "ref": "main",
-        "rev": "c4da43da0f583bd3cbcfd1f3acf74f9dc51b8fdd",
+        "rev": "7e97734797f0c6bd3c2d3a51cf54a2a6b371c222",
         "shallow": true,
         "type": "git",
         "url": "https://git.clan.lol/clan/clan-core"
@@ -84,11 +84,11 @@
     },
     "nixpkgs-dev": {
       "locked": {
-        "lastModified": 1756104823,
-        "narHash": "sha256-wRzHREXDOrbCjy+sqo4t3JoInbB2PuhXIUa8NWdh9tk=",
+        "lastModified": 1755166611,
+        "narHash": "sha256-sk8pK8kWz4IE4ErAjKE1d8tMChY6VQR32U4yS68FIog=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "d7967bed5381e65208f4fb8d5502e3c36bb94759",
+        "rev": "1a341e3c908f4a3105e737bd13af0318dc06fbe3",
         "type": "github"
       },
       "original": {
@@ -107,11 +107,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1755555503,
-        "narHash": "sha256-WiOO7GUOsJ4/DoMy2IC5InnqRDSo2U11la48vCCIjjY=",
+        "lastModified": 1754869408,
+        "narHash": "sha256-G1zNuxiCDfqNQVoL9j5v+ZYfUER7AI158ev98/JC8LI=",
         "owner": "NuschtOS",
         "repo": "search",
-        "rev": "6f3efef888b92e6520f10eae15b86ff537e1d2ea",
+        "rev": "2f5478267557a0f7a70d953b6c0867a5b4282739",
         "type": "github"
       },
       "original": {
@@ -165,11 +165,11 @@
         "nixpkgs": []
       },
       "locked": {
-        "lastModified": 1755934250,
-        "narHash": "sha256-CsDojnMgYsfshQw3t4zjRUkmMmUdZGthl16bXVWgRYU=",
+        "lastModified": 1754847726,
+        "narHash": "sha256-2vX8QjO5lRsDbNYvN9hVHXLU6oMl+V/PsmIiJREG4rE=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "74e1a52d5bd9430312f8d1b8b0354c92c17453e5",
+        "rev": "7d81f6fb2e19bf84f1c65135d1060d829fae2408",
         "type": "github"
       },
       "original": {

devShell.nix

@@ -33,6 +33,7 @@
           self'.packages.tea-create-pr
           self'.packages.merge-after-ci
           self'.packages.pending-reviews
+          self'.packages.agit
           # treefmt with config defined in ./flake-parts/formatting.nix
           config.treefmt.build.wrapper
         ];
@@ -45,7 +46,7 @@
           ln -sfT ${inputs.nix-select} "$PRJ_ROOT/pkgs/clan-cli/clan_lib/select"
 
           # Generate classes.py from schemas
-          ${self'.packages.classgen}/bin/classgen ${self'.legacyPackages.schemas.clanSchemaJson}/schema.json $PRJ_ROOT/pkgs/clan-cli/clan_lib/nix_models/clan.py
+          ${self'.packages.classgen}/bin/classgen ${self'.legacyPackages.schemas.clan-schema-abstract}/schema.json $PRJ_ROOT/pkgs/clan-cli/clan_lib/nix_models/clan.py
         '';
       };
     };

docs/.gitignore

@@ -1,5 +1,5 @@
 /site/reference
 /site/static
-/site/options
+/site/options-page
 /site/openapi.json
 !/site/static/extra.css

docs/CONTRIBUTING.md

@@ -1,12 +1,9 @@
 # Contributing to Clan
 
-**Continuous Integration (CI)**: Each pull request gets automatically tested by
-gitea. If any errors are detected, it will block pull requests until they're
-resolved.
 
-**Dependency Management**: We use the [Nix package manager](https://nixos.org/)
-to manage dependencies and ensure reproducibility, making your development
-process more robust.
+**Continuous Integration (CI)**: Each pull request gets automatically tested by gitea. If any errors are detected, it will block pull requests until they're resolved.
+
+**Dependency Management**: We use the [Nix package manager](https://nixos.org/) to manage dependencies and ensure reproducibility, making your development process more robust.
 
 ## Supported Operating Systems
 
@@ -19,81 +16,68 @@ Let's get your development environment up and running:
 
 1. **Install Nix Package Manager**:
 
-   - You can install the Nix package manager by either
-     [downloading the Nix installer](https://github.com/DeterminateSystems/nix-installer/releases)
-     or running this command:
-     ```bash
-     curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-     ```
+      - You can install the Nix package manager by either [downloading the Nix installer](https://github.com/DeterminateSystems/nix-installer/releases) or running this command:
+        ```bash
+        curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+        ```
 
-2. **Install direnv**:
+1. **Install direnv**:
 
-   - To automatically setup a devshell on entering the directory
-     ```bash
-     nix profile install nixpkgs#nix-direnv-flakes nixpkgs#direnv
-     ```
+      - To automatically setup a devshell on entering the directory
+        ```bash
+        nix profile install nixpkgs#nix-direnv-flakes nixpkgs#direnv
+        ```
 
-3. **Add direnv to your shell**:
+1. **Add direnv to your shell**:
 
-   - Direnv needs to [hook into your shell](https://direnv.net/docs/hook.html)
-     to work. You can do this by executing following command. The example below
-     will setup direnv for `zsh` and `bash`
+      - Direnv needs to [hook into your shell](https://direnv.net/docs/hook.html) to work.
+        You can do this by executing following command. The example below will setup direnv for `zsh` and `bash`
 
-   ```bash
-   echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
-   ```
+      ```bash
+      echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
+      ```
 
-4. **Allow the devshell**
+1. **Allow the devshell**
+      - Go to `clan-core/pkgs/clan-cli` and do a `direnv allow` to setup the necessary development environment to execute the `clan` command
 
-   - Go to `clan-core/pkgs/clan-cli` and do a `direnv allow` to setup the
-     necessary development environment to execute the `clan` command
+1. **Create a Gitea Account**:
+      - Register an account on https://git.clan.lol
+      - Fork the [clan-core](https://git.clan.lol/clan/clan-core) repository
+      - Clone the repository and navigate to it
+      - Add a new remote called upstream:
+         ```bash
+         git remote add upstream gitea@git.clan.lol:clan/clan-core.git
+         ```
+1. **Allow .envrc**:
 
-5. **Create a Gitea Account**:
+      - When you enter the directory, you'll receive an error message like this:
+        ```bash
+        direnv: error .envrc is blocked. Run `direnv allow` to approve its content
+        ```
+      - Execute `direnv allow` to automatically execute the shell script `.envrc` when entering the directory.
 
-   - Register an account on https://git.clan.lol
-   - Fork the [clan-core](https://git.clan.lol/clan/clan-core) repository
-   - Clone the repository and navigate to it
-   - Add a new remote called upstream:
-     ```bash
-     git remote add upstream gitea@git.clan.lol:clan/clan-core.git
-     ```
-
-6. **Allow .envrc**:
-
-   - When you enter the directory, you'll receive an error message like this:
-     ```bash
-     direnv: error .envrc is blocked. Run `direnv allow` to approve its content
-     ```
-   - Execute `direnv allow` to automatically execute the shell script `.envrc`
-     when entering the directory.
-
-7. **(Optional) Install Git Hooks**:
-
-   - To syntax check your code you can run:
-     ```bash
-     nix fmt
-     ```
-   - To make this automatic install the git hooks
-     ```bash
-     ./scripts/pre-commit
-     ```
+1. **(Optional) Install Git Hooks**:
+      - To syntax check your code you can run:
+         ```bash
+         nix fmt
+         ```
+      - To make this automatic install the git hooks
+         ```bash
+         ./scripts/pre-commit
+         ```
 
 ## Related Projects
 
 - **Data Mesher**: [data-mesher](https://git.clan.lol/clan/data-mesher)
-- **Nixos Facter**:
-  [nixos-facter](https://github.com/nix-community/nixos-facter)
-- **Nixos Anywhere**:
-  [nixos-anywhere](https://github.com/nix-community/nixos-anywhere)
+- **Nixos Facter**: [nixos-facter](https://github.com/nix-community/nixos-facter)
+- **Nixos Anywhere**: [nixos-anywhere](https://github.com/nix-community/nixos-anywhere)
 - **Disko**: [disko](https://github.com/nix-community/disko)
 
 ## Fixing Bugs or Adding Features in Clan-CLI
 
-If you have a bug fix or feature that involves a related project, clone the
-relevant repository and replace its invocation in your local setup.
+If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup.
 
-For instance, if you need to update `nixos-anywhere` in clan-cli, find its
-usage:
+For instance, if you need to update `nixos-anywhere` in clan-cli, find its usage:
 
 ```python
 run(
@@ -118,8 +102,7 @@ run(
 
 ```
 
-The \<path_to_local_src> doesn't need to be a local path, it can be any valid
-[flakeref](https://nix.dev/manual/nix/2.26/command-ref/new-cli/nix3-flake.html#flake-references).
+The <path_to_local_src> doesn't need to be a local path, it can be any valid [flakeref](https://nix.dev/manual/nix/2.26/command-ref/new-cli/nix3-flake.html#flake-references).
 And thus can point to test already opened PRs for example.
 
 # Standards
@@ -127,5 +110,4 @@ And thus can point to test already opened PRs for example.
 - Every new module name should be in kebab-case.
 - Every fact definition, where possible should be in kebab-case.
 - Every vars definition, where possible should be in kebab-case.
-- Command line help descriptions should start capitalized and should not end in
-  a period.
+- Command line help descriptions should start capitalized and should not end in a period.

docs/_internal/use-cases/01-self-host.md

@@ -2,27 +2,17 @@
 
 ## General Description
 
-Self-hosting refers to the practice of hosting and maintaining servers,
-networks, storage, services, and other types of infrastructure by oneself rather
-than relying on a third-party vendor. This could involve running a server from a
-home or business location, or leasing a dedicated server at a data center.
+Self-hosting refers to the practice of hosting and maintaining servers, networks, storage, services, and other types of infrastructure by oneself rather than relying on a third-party vendor. This could involve running a server from a home or business location, or leasing a dedicated server at a data center.
 
 There are several reasons for choosing to self-host. These can include:
 
-1. Cost savings: Over time, self-hosting can be more cost-effective, especially
-   for businesses with large scale needs.
+1. Cost savings: Over time, self-hosting can be more cost-effective, especially for businesses with large scale needs.
 
-2. Control: Self-hosting provides a greater level of control over the
-   infrastructure and services. It allows the owner to customize the system to
-   their specific needs.
+1. Control: Self-hosting provides a greater level of control over the infrastructure and services. It allows the owner to customize the system to their specific needs.
 
-3. Privacy and security: Self-hosting can offer improved privacy and security
-   because data remains under the control of the host rather than being stored
-   on third-party servers.
+1. Privacy and security: Self-hosting can offer improved privacy and security because data remains under the control of the host rather than being stored on third-party servers.
 
-4. Independent: Being independent of third-party services can ensure that one's
-   websites, applications, or services remain up even if the third-party service
-   goes down.
+1. Independent: Being independent of third-party services can ensure that one's websites, applications, or services remain up even if the third-party service goes down.
 
 ## Stories
 
@@ -30,32 +20,23 @@ There are several reasons for choosing to self-host. These can include:
 
 Alice wants to self-host a mumble server for her family.
 
-- She visits to the Clan website, and follows the instructions on how to install
-  Clan-OS on her server.
-- Alice logs into a terminal on her server via SSH (alternatively uses Clan GUI
-  app)
-- Using the Clan CLI or GUI tool, alice creates a new private network for her
-  family (VPN)
-- Alice now browses a list of curated Clan modules and finds a module for
-  mumble.
+- She visits to the Clan website, and follows the instructions on how to install Clan-OS on her server.
+- Alice logs into a terminal on her server via SSH (alternatively uses Clan GUI app)
+- Using the Clan CLI or GUI tool, alice creates a new private network for her family (VPN)
+- Alice now browses a list of curated Clan modules and finds a module for mumble.
 - She adds this module to her network using the Clan tool.
 - After that, she uses the clan tool to invite her family members to her network
 - Other family members join the private network via the invitation.
-- By accepting the invitation, other members automatically install all required
-  software to interact with the network on their machine.
+- By accepting the invitation, other members automatically install all required software to interact with the network on their machine.
 
 ### Story 2: Adding a service to an existing network
 
 Alice wants to add a photos app to her private network
 
-- She uses the clan CLI or GUI tool to manage her existing private Clan family
-  network
-- She discovers a module for photoprism, and adds it to her server using the
-  tool
-- Other members who are already part of her network, will receive a notification
-  that an update is required to their environment
-- After accepting, all new software and services to interact with the new
-  photoprism service will be installed automatically.
+- She uses the clan CLI or GUI tool to manage her existing private Clan family network
+- She discovers a module for photoprism, and adds it to her server using the tool
+- Other members who are already part of her network, will receive a notification that an update is required to their environment
+- After accepting, all new software and services to interact with the new photoprism service will be installed automatically.
 
 ## Challenges
 

docs/_internal/use-cases/02-join-network.md

@@ -2,53 +2,35 @@
 
 ## General Description
 
-Joining a self-hosted infrastructure involves connecting to a network, server,
-or system that is privately owned and managed, instead of being hosted by a
-third-party service provider. This could be a business's internal server, a
-private cloud setup, or any other private IT infrastructure that is not publicly
-accessible or controlled by outside entities.
+Joining a self-hosted infrastructure involves connecting to a network, server, or system that is privately owned and managed, instead of being hosted by a third-party service provider. This could be a business's internal server, a private cloud setup, or any other private IT infrastructure that is not publicly accessible or controlled by outside entities.
 
 ## Stories
 
 ### Story 1: Joining a private network
 
-Alice' son Bob has never heard of Clan, but receives an invitation URL from
-Alice who already set up private Clan network for her family.
+Alice' son Bob has never heard of Clan, but receives an invitation URL from Alice who already set up private Clan network for her family.
 
-Bob opens the invitation link and lands on the Clan website. He quickly learns
-about what Clan is and can see that the invitation is for a private network of
-his family that hosts a number of services, like a private voice chat and a
-photo sharing platform.
+Bob opens the invitation link and lands on the Clan website. He quickly learns about what Clan is and can see that the invitation is for a private network of his family that hosts a number of services, like a private voice chat and a photo sharing platform.
 
-Bob decides to join the network and follows the instructions to install the Clan
-tool on his computer.
+Bob decides to join the network and follows the instructions to install the Clan tool on his computer.
 
-Feeding the invitation link to the Clan tool, bob registers his machine with the
-network.
+Feeding the invitation link to the Clan tool, bob registers his machine with the network.
 
-All programs required to interact with the network will be installed and
-configured automatically and securely.
+All programs required to interact with the network will be installed and configured automatically and securely.
 
-Optionally, bob can customize the configuration of these programs through a
-simplified configuration interface.
+Optionally, bob can customize the configuration of these programs through a simplified configuration interface.
 
 ### Story 2: Receiving breaking changes
 
 The Clan family network which Bob is part of received an update.
 
-The existing photo sharing service has been removed and replaced with another
-alternative service. The new photo sharing service requires a different client
-app to view and upload photos.
+The existing photo sharing service has been removed and replaced with another alternative service. The new photo sharing service requires a different client app to view and upload photos.
 
-Bob accepts the update. Now his environment will be updated. The old client
-software will be removed and the new one installed.
+Bob accepts the update. Now his environment will be updated. The old client software will be removed and the new one installed.
 
-Because Bob has customized the previous photo viewing app, he is notified that
-this customization is no longer valid, as the software has been removed
-(deprecation message).l
+Because Bob has customized the previous photo viewing app, he is notified that this customization is no longer valid, as the software has been removed (deprecation message).l
 
-Optionally, Bob can now customize the new photo viewing software through his
-Clan configuration app or via a config file.
+Optionally, Bob can now customize the new photo viewing software through his Clan configuration app or via a config file.
 
 ## Challenges
 

docs/_internal/use-cases/03-maintaining-clan-modules.md

@@ -2,30 +2,23 @@
 
 ## General Description
 
-Clan modules are pieces of software that can be used by admins to build a
-private or public infrastructure.
+Clan modules are pieces of software that can be used by admins to build a private or public infrastructure.
 
 Clan modules should have the following properties:
 
 1. Documented: It should be clear what the module does and how to use it.
-2. Self contained: A module should be usable as is. If it requires any other
-   software or settings, those should be delivered with the module itself.
-3. Simple to deploy and use: Modules should have opinionated defaults that just
-   work. Any customization should be optional
+1. Self contained: A module should be usable as is. If it requires any other software or settings, those should be delivered with the module itself.
+1. Simple to deploy and use: Modules should have opinionated defaults that just work. Any customization should be optional
 
 ## Stories
 
 ### Story 1: Maintaining a shared folder module
 
-Alice maintains a module for a shared folder service that she uses in her own
-infra, but also publishes for the community.
+Alice maintains a module for a shared folder service that she uses in her own infra, but also publishes for the community.
 
-By following clan module standards (Backups, Interfaces, Output schema, etc),
-other community members have an easy time re-using the module within their own
-infra.
+By following clan module standards (Backups, Interfaces, Output schema, etc), other community members have an easy time re-using the module within their own infra.
 
-She benefits from publishing the module, because other community members start
-using it and help to maintain it.
+She benefits from publishing the module, because other community members start using it and help to maintain it.
 
 ## Challenges
 

docs/mkdocs.yml

@@ -6,7 +6,7 @@ edit_uri: _edit/main/docs/docs/
 
 validation:
   omitted_files: warn
-  absolute_links: ignore
+  absolute_links: warn
   unrecognized_links: warn
 
 markdown_extensions:
@@ -59,15 +59,14 @@ nav:
           - Configure Disk Config: guides/getting-started/choose-disk.md
           - Update Machine: guides/getting-started/update.md
           - Continuous Integration: guides/getting-started/flake-check.md
-          - Convert Existing NixOS Config: guides/getting-started/convert-flake.md
-      - ClanServices: guides/clanServices.md
+      - Using Services: guides/clanServices.md
       - Backup & Restore: guides/backups.md
       - Disk Encryption: guides/disk-encryption.md
       - Age Plugins: guides/age-plugins.md
       - Secrets management: guides/secrets.md
-      - Networking: guides/networking.md
+      - Target Host: guides/target-host.md
       - Zerotier VPN: guides/mesh-vpn.md
-      - How to disable Secure Boot: guides/secure-boot.md
+      - Secure Boot: guides/secure-boot.md
       - Flake-parts: guides/flake-parts.md
       - macOS: guides/macos.md
       - Contributing:
@@ -78,7 +77,8 @@ nav:
       - Writing a Service Module: guides/services/community.md
       - Writing a Disko Template: guides/disko-templates/community.md
       - Migrations:
-          - Migrate from clan modules to services: guides/migrations/migrate-inventory-services.md
+          - Migrate existing Flakes: guides/migrations/migration-guide.md
+          - Migrate inventory Services: guides/migrations/migrate-inventory-services.md
           - Facts Vars Migration: guides/migrations/migration-facts-vars.md
           - Disk id: guides/migrations/disk-id.md
   - Concepts:
@@ -88,7 +88,7 @@ nav:
       - Templates: concepts/templates.md
   - Reference:
       - Overview: reference/index.md
-      - Browse Options: "/options"
+      - Clan Options: options.md
       - Services:
           - Overview:
               - reference/clanServices/index.md
@@ -155,7 +155,6 @@ nav:
           - 05-deployment-parameters: decisions/05-deployment-parameters.md
           - Template: decisions/_template.md
       - Glossary: reference/glossary.md
-  - Browse Options: "/options"
 
 docs_dir: site
 site_dir: out

docs/nix/default.nix

@@ -54,9 +54,9 @@ pkgs.stdenv.mkDerivation {
     chmod -R +w ./site/reference
     echo "Generated API documentation in './site/reference/' "
 
-    rm -rf ./site/options
-    cp -r ${docs-options} ./site/options
-    chmod -R +w ./site/options
+    rm -r ./site/options-page || true
+    cp -r ${docs-options} ./site/options-page
+    chmod -R +w ./site/options-page
 
     mkdir -p ./site/static/asciinema-player
     ln -snf ${asciinema-player-js} ./site/static/asciinema-player/asciinema-player.min.js

docs/nix/deploy-docs.nix

@@ -40,7 +40,6 @@ writeShellScriptBin "deploy-docs" ''
 
   rsync \
     --checksum \
-    --delete \
     -e "ssh -o StrictHostKeyChecking=no $sshExtraArgs" \
     -a ${docs}/ \
     www@clan.lol:/var/www/docs.clan.lol

docs/nix/flake-module.nix

@@ -18,8 +18,27 @@
         inherit (self) clanModules;
         clan-core = self;
         inherit pkgs;
+        evalClanModules = self.clanLib.evalClan.evalClanModules;
+        modulesRolesOptions = self.clanLib.evalClan.evalClanModulesWithRoles {
+          allModules = self.clanModules;
+          inherit pkgs;
+          clan-core = self;
+        };
       };
 
+      # Frontmatter for clanModules
+      clanModulesFrontmatter =
+        let
+          docs = pkgs.nixosOptionsDoc {
+            options = self.clanLib.modules.frontmatterOptions;
+            transformOptions = self.clanLib.docs.stripStorePathsFromDeclarations;
+          };
+        in
+        docs.optionsJSON;
+
+      # Options available when imported via ` inventory.${moduleName}....${rolesName} `
+      clanModulesViaRoles = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaRoles);
+
       # clan service options
       clanModulesViaService = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaService);
 
@@ -69,10 +88,12 @@
               }
             }
             export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json
-
             # A file that contains the links to all clanModule docs
+            export CLAN_MODULES_VIA_ROLES=${clanModulesViaRoles}
             export CLAN_MODULES_VIA_SERVICE=${clanModulesViaService}
             export CLAN_SERVICE_INTERFACE=${self'.legacyPackages.clan-service-module-interface}/share/doc/nixos/options.json
+            # Frontmatter format for clanModules
+            export CLAN_MODULES_FRONTMATTER_DOCS=${clanModulesFrontmatter}/share/doc/nixos/options.json
 
             export BUILD_CLAN_PATH=${buildClanOptions}/share/doc/nixos/options.json
 
@@ -86,6 +107,7 @@
       legacyPackages = {
         inherit
           jsonDocs
+          clanModulesViaRoles
           clanModulesViaService
           ;
       };

docs/nix/get-module-docs.nix

@@ -1,5 +1,7 @@
 {
+  modulesRolesOptions,
   nixosOptionsDoc,
+  evalClanModules,
   lib,
   pkgs,
   clan-core,
@@ -8,36 +10,21 @@
 let
   inherit (clan-core.clanLib.docs) stripStorePathsFromDeclarations;
   transformOptions = stripStorePathsFromDeclarations;
-
-  nixosConfigurationWithClan =
-    let
-      evaled = lib.evalModules {
-        class = "nixos";
-        modules = [
-          # Basemodule
-          (
-            { config, ... }:
-            {
-              imports = (import (pkgs.path + "/nixos/modules/module-list.nix"));
-              nixpkgs.pkgs = pkgs;
-              clan.core.name = "dummy";
-              system.stateVersion = config.system.nixos.release;
-              # Set this to work around a bug where `clan.core.settings.machine.name`
-              # is forced due to `networking.interfaces` being forced
-              # somewhere in the nixpkgs options
-              facter.detected.dhcp.enable = lib.mkForce false;
-            }
-          )
-          {
-            clan.core.settings.directory = clan-core;
-          }
-          clan-core.nixosModules.clanCore
-        ];
-      };
-    in
-    evaled;
 in
 {
+
+  clanModulesViaRoles = lib.mapAttrs (
+    _moduleName: rolesOptions:
+    lib.mapAttrs (
+      _roleName: options:
+      (nixosOptionsDoc {
+        inherit options;
+        warningsAreErrors = true;
+        inherit transformOptions;
+      }).optionsJSON
+    ) rolesOptions
+  ) modulesRolesOptions;
+
   # Test with:
   # nix build .\#legacyPackages.x86_64-linux.clanModulesViaService
   clanModulesViaService = lib.mapAttrs (
@@ -51,6 +38,7 @@ in
     {
       roles = lib.mapAttrs (
         _roleName: role:
+
         (nixosOptionsDoc {
           transformOptions =
             opt:
@@ -66,13 +54,20 @@ in
           warningsAreErrors = true;
         }).optionsJSON
       ) evaluatedService.config.roles;
+
       manifest = evaluatedService.config.manifest;
+
     }
   ) clan-core.clan.modules;
 
   clanCore =
     (nixosOptionsDoc {
-      options = nixosConfigurationWithClan.options.clan.core;
+      options =
+        ((evalClanModules {
+          modules = [ ];
+          inherit pkgs clan-core;
+        }).options
+        ).clan.core or { };
       warningsAreErrors = true;
       inherit transformOptions;
     }).optionsJSON;

docs/nix/options/flake-module.nix

@@ -25,7 +25,7 @@
 
       serviceModules = self.clan.modules;
 
-      baseHref = "/options/";
+      baseHref = "/options-page/";
 
       getRoles =
         module:
@@ -126,7 +126,7 @@
                           nestedSettingsOption = mkOption {
                             type = types.raw;
                             description = ''
-                              See [instances.${name}.roles.${roleName}.settings](${baseHref}?option_scope=0&option=inventory.instances.${name}.roles.${roleName}.settings)
+                              See [instances.${name}.roles.${roleName}.settings](${baseHref}?option_scope=0&option=instances.${name}.roles.${roleName}.settings)
                             '';
                           };
                           settingsOption = mkOption {
@@ -161,42 +161,6 @@
         }
       ];
 
-      baseModule =
-        # Module
-        { config, ... }:
-        {
-          imports = (import (pkgs.path + "/nixos/modules/module-list.nix"));
-          nixpkgs.pkgs = pkgs;
-          clan.core.name = "dummy";
-          system.stateVersion = config.system.nixos.release;
-          # Set this to work around a bug where `clan.core.settings.machine.name`
-          # is forced due to `networking.interfaces` being forced
-          # somewhere in the nixpkgs options
-          facter.detected.dhcp.enable = lib.mkForce false;
-        };
-
-      evalClanModules =
-        let
-          evaled = lib.evalModules {
-            class = "nixos";
-            modules = [
-              baseModule
-              {
-                clan.core.settings.directory = self;
-              }
-              self.nixosModules.clanCore
-            ];
-          };
-        in
-        evaled;
-
-      coreOptions =
-        (pkgs.nixosOptionsDoc {
-          options = (evalClanModules.options).clan.core or { };
-          warningsAreErrors = true;
-          transformOptions = self.clanLib.docs.stripStorePathsFromDeclarations;
-        }).optionsJSON;
-
     in
     {
       # Uncomment for debugging
@@ -211,17 +175,10 @@
           # scopes = mapAttrsToList mkScope serviceModules;
           scopes = [
             {
-              inherit baseHref;
-              name = "Flake Options (clan.nix file)";
+              name = "Clan";
               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";
-              urlPrefix = "https://git.clan.lol/clan/clan-core/src/branch/main/";
-
-            }
           ];
         };
       };

docs/nix/render_options/__init__.py

@@ -1,5 +1,3 @@
-"""Module for rendering NixOS options documentation from JSON format."""
-
 # Options are available in the following format:
 # https://github.com/nixos/nixpkgs/blob/master/nixos/lib/make-options-doc/default.nix
 #
@@ -34,14 +32,23 @@ from typing import Any
 from clan_lib.errors import ClanError
 from clan_lib.services.modules import (
     CategoryInfo,
-    ModuleManifest,
+    Frontmatter,
+    extract_frontmatter,
+    get_roles,
 )
 
 # Get environment variables
 CLAN_CORE_PATH = Path(os.environ["CLAN_CORE_PATH"])
 CLAN_CORE_DOCS = Path(os.environ["CLAN_CORE_DOCS"])
+CLAN_MODULES_FRONTMATTER_DOCS = os.environ.get("CLAN_MODULES_FRONTMATTER_DOCS")
 BUILD_CLAN_PATH = os.environ.get("BUILD_CLAN_PATH")
 
+## Clan modules ##
+# Some modules can be imported via nix natively
+CLAN_MODULES_VIA_NIX = os.environ.get("CLAN_MODULES_VIA_NIX")
+# Some modules can be imported via inventory
+CLAN_MODULES_VIA_ROLES = os.environ.get("CLAN_MODULES_VIA_ROLES")
+
 # Options how to author clan.modules
 # perInstance, perMachine, ...
 CLAN_SERVICE_INTERFACE = os.environ.get("CLAN_SERVICE_INTERFACE")
@@ -68,7 +75,8 @@ def render_option_header(name: str) -> str:
 
 
 def join_lines_with_indentation(lines: list[str], indent: int = 4) -> str:
-    """Joins multiple lines with a specified number of whitespace characters as indentation.
+    """
+    Joins multiple lines with a specified number of whitespace characters as indentation.
 
     Args:
     lines (list of str): The lines of text to join.
@@ -76,7 +84,6 @@ def join_lines_with_indentation(lines: list[str], indent: int = 4) -> str:
 
     Returns:
     str: The indented and concatenated string.
-
     """
     # Create the indentation string (e.g., four spaces)
     indent_str = " " * indent
@@ -163,10 +170,7 @@ def render_option(
 
 
 def print_options(
-    options_file: str,
-    head: str,
-    no_options: str,
-    replace_prefix: str | None = None,
+    options_file: str, head: str, no_options: str, replace_prefix: str | None = None
 ) -> str:
     res = ""
     with (Path(options_file) / "share/doc/nixos/options.json").open() as f:
@@ -175,16 +179,32 @@ def print_options(
         res += head if len(options.items()) else no_options
         for option_name, info in options.items():
             if replace_prefix:
-                display_name = option_name.replace(replace_prefix + ".", "")
-            else:
-                display_name = option_name
+                option_name = option_name.replace(replace_prefix + ".", "")
 
-            res += render_option(display_name, info, 4)
+            res += render_option(option_name, info, 4)
     return res
 
 
-def module_header(module_name: str) -> str:
-    return f"# {module_name}\n\n"
+def module_header(module_name: str, has_inventory_feature: bool = False) -> str:
+    indicator = " 🔹" if has_inventory_feature else ""
+    return f"# {module_name}{indicator}\n\n"
+
+
+def module_nix_usage(module_name: str) -> str:
+    return f"""## Usage via Nix
+
+**This module can be also imported directly in your nixos configuration. Although it is recommended to use the [inventory](../../concepts/inventory.md) interface if available.**
+
+Some modules are considered 'low-level' or 'expert modules' and are not available via the inventory interface.
+
+```nix
+{{config, lib, inputs, ...}}: {{
+    imports = [ inputs.clan-core.clanModules.{module_name} ];
+    # ...
+}}
+```
+
+"""
 
 
 clan_core_descr = """
@@ -203,6 +223,68 @@ The following options are available for this module.
 """
 
 
+def produce_clan_modules_frontmatter_docs() -> None:
+    if not CLAN_MODULES_FRONTMATTER_DOCS:
+        msg = f"Environment variables are not set correctly: $CLAN_CORE_DOCS={CLAN_CORE_DOCS}"
+        raise ClanError(msg)
+
+    if not OUT:
+        msg = f"Environment variables are not set correctly: $out={OUT}"
+        raise ClanError(msg)
+
+    with Path(CLAN_MODULES_FRONTMATTER_DOCS).open() as f:
+        options: dict[str, dict[str, Any]] = json.load(f)
+
+        # header
+        output = """# Frontmatter
+
+Every clan module has a `frontmatter` section within its readme. It provides
+machine readable metadata about the module.
+
+!!! example
+
+    The used format is `TOML`
+
+    The content is separated by `---` and the frontmatter must be placed at the very top of the `README.md` file.
+
+    ```toml
+    ---
+    description = "A description of the module"
+    categories = ["category1", "category2"]
+
+    [constraints]
+    roles.client.max = 10
+    roles.server.min = 1
+    ---
+    # Readme content
+    ...
+    ```
+
+"""
+
+        output += """## Overview
+
+This provides an overview of the available attributes of the `frontmatter`
+within the `README.md` of a clan module.
+
+"""
+        # for option_name, info in options.items():
+        #     if option_name == "_module.args":
+        #         continue
+        #     output += render_option(option_name, info)
+        root = options_to_tree(options, debug=True)
+        for option in root.suboptions:
+            output += options_docs_from_tree(option, init_level=2)
+
+        outfile = Path(OUT) / "clanModules/frontmatter/index.md"
+        outfile.parent.mkdir(
+            parents=True,
+            exist_ok=True,
+        )
+        with outfile.open("w") as of:
+            of.write(output)
+
+
 def produce_clan_core_docs() -> None:
     if not CLAN_CORE_DOCS:
         msg = f"Environment variables are not set correctly: $CLAN_CORE_DOCS={CLAN_CORE_DOCS}"
@@ -242,7 +324,7 @@ def produce_clan_core_docs() -> None:
         for submodule_name, split_options in split.items():
             outfile = f"{module_name}/{submodule_name}.md"
             print(
-                f"[clan_core.{submodule_name}] Rendering option of: {submodule_name}... {outfile}",
+                f"[clan_core.{submodule_name}] Rendering option of: {submodule_name}... {outfile}"
             )
             init_level = 1
             root = options_to_tree(split_options, debug=True)
@@ -277,9 +359,56 @@ def produce_clan_core_docs() -> None:
                 of.write(output)
 
 
+def render_roles(roles: list[str] | None, module_name: str) -> str:
+    if roles:
+        roles_list = "\n".join([f"- `{r}`" for r in roles])
+        return (
+            f"""
+### Roles
+
+This module can be used via predefined roles
+
+{roles_list}
+"""
+            """
+Every role has its own configuration options, which are each listed below.
+
+For more information, see the [inventory guide](../../concepts/inventory.md).
+
+??? Example
+    For example the `admin` module adds the following options globally to all machines where it is used.
+
+    `clan.admin.allowedkeys`
+
+    ```nix
+    clan-core.lib.clan {
+        inventory.services = {
+            admin.me = {
+                roles.default.machines = [ "jon" ];
+                config.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ];
+            };
+        };
+    };
+    ```
+"""
+        )
+    return ""
+
+
+clan_modules_descr = """
+Clan modules are [NixOS modules](https://wiki.nixos.org/wiki/NixOS_modules)
+which have been enhanced with additional features provided by Clan, with
+certain option types restricted to enable configuration through a graphical
+interface.
+
+!!! note "🔹"
+    Modules with this indicator support the [inventory](../../concepts/inventory.md) feature.
+
+"""
+
+
 def render_categories(
-    categories: list[str],
-    categories_info: dict[str, CategoryInfo],
+    categories: list[str], categories_info: dict[str, CategoryInfo]
 ) -> str:
     res = """<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px;">"""
     for cat in categories:
@@ -344,10 +473,10 @@ Learn how to use `clanServices` in practice in the [Using clanServices guide](..
         # output += f"`clan.modules.{module_name}`\n"
         output += f"*{module_info['manifest']['description']}*\n"
 
+        fm = Frontmatter("")
         # output += "## Categories\n\n"
         output += render_categories(
-            module_info["manifest"]["categories"],
-            ModuleManifest.categories_info(),
+            module_info["manifest"]["categories"], fm.categories_info
         )
 
         output += f"{module_info['manifest']['readme']}\n"
@@ -356,7 +485,7 @@ Learn how to use `clanServices` in practice in the [Using clanServices guide](..
 
         output += f"The {module_name} module has the following roles:\n\n"
 
-        for role_name in module_info["roles"]:
+        for role_name, _ in module_info["roles"].items():
             output += f"- {role_name}\n"
 
         for role_name, role_filename in module_info["roles"].items():
@@ -376,8 +505,183 @@ Learn how to use `clanServices` in practice in the [Using clanServices guide](..
             of.write(output)
 
 
+def produce_clan_modules_docs() -> None:
+    if not CLAN_MODULES_VIA_NIX:
+        msg = f"Environment variables are not set correctly: $CLAN_MODULES_VIA_NIX={CLAN_MODULES_VIA_NIX}"
+        raise ClanError(msg)
+
+    if not CLAN_MODULES_VIA_ROLES:
+        msg = f"Environment variables are not set correctly: $CLAN_MODULES_VIA_ROLES={CLAN_MODULES_VIA_ROLES}"
+        raise ClanError(msg)
+
+    if not CLAN_CORE_PATH:
+        msg = f"Environment variables are not set correctly: $CLAN_CORE_PATH={CLAN_CORE_PATH}"
+        raise ClanError(msg)
+
+    if not OUT:
+        msg = f"Environment variables are not set correctly: $out={OUT}"
+        raise ClanError(msg)
+
+    modules_index = "# Modules Overview\n\n"
+    modules_index += clan_modules_descr
+    modules_index += "## Overview\n\n"
+    modules_index += '<div class="grid cards" markdown>\n\n'
+
+    with Path(CLAN_MODULES_VIA_ROLES).open() as f2:
+        role_links: dict[str, dict[str, str]] = json.load(f2)
+
+    with Path(CLAN_MODULES_VIA_NIX).open() as f:
+        links: dict[str, str] = json.load(f)
+
+    for module_name, options_file in links.items():
+        print(f"Rendering ClanModule: {module_name}")
+        readme_file = CLAN_CORE_PATH / "clanModules" / module_name / "README.md"
+        with readme_file.open() as f:
+            readme = f.read()
+            frontmatter: Frontmatter
+            frontmatter, readme_content = extract_frontmatter(readme, str(readme_file))
+
+        # skip if experimental feature enabled
+        if "experimental" in frontmatter.features:
+            print(f"Skipping {module_name}: Experimental feature")
+            continue
+
+        modules_index += build_option_card(module_name, frontmatter)
+
+        ##### Print module documentation #####
+
+        # 1. Header
+        output = module_header(module_name, "inventory" in frontmatter.features)
+
+        # 2. Description from README.md
+        if frontmatter.description:
+            output += f"*{frontmatter.description}*\n\n"
+
+        # 2. Deprecation note if the module is deprecated
+        if "deprecated" in frontmatter.features:
+            output += f"""
+!!! Warning "Deprecated"
+    The `{module_name}` module is deprecated.*
+
+    Use 'clanServices/{module_name}' or a similar successor instead
+"""
+        else:
+            output += f"""
+!!! Warning "Will be deprecated"
+    The `{module_name}` module might eventually be migrated to 'clanServices'*
+
+    See: [clanServices](../../guides/clanServices.md)
+"""
+
+        # 3. Categories from README.md
+        output += "## Categories\n\n"
+        output += render_categories(frontmatter.categories, frontmatter.categories_info)
+        output += "\n---\n\n"
+
+        # 3. README.md content
+        output += f"{readme_content}\n"
+
+        # 4. Usage
+        ##### Print usage via Inventory #####
+
+        # get_roles(str) -> list[str] | None
+        # if not isinstance(options_file, str):
+        roles = get_roles(CLAN_CORE_PATH / "clanModules" / module_name)
+        if roles:
+            # Render inventory usage
+            output += """## Usage via Inventory\n\n"""
+            output += render_roles(roles, module_name)
+            for role in roles:
+                role_options_file = role_links[module_name][role]
+                # Abort if the options file is not found
+                if not isinstance(role_options_file, str):
+                    print(
+                        f"Error: module: {module_name} in role: {role} - options file not found, Got {role_options_file}"
+                    )
+                    exit(1)
+
+                no_options = f"""### Options of `{role}` role
+
+**The `{module_name}` `{role}` doesnt offer / require any options to be set.**
+"""
+
+                heading = f"""### Options of `{role}` role
+
+The following options are available when using the `{role}` role.
+"""
+                output += print_options(
+                    role_options_file,
+                    heading,
+                    no_options,
+                    replace_prefix=f"clan.{module_name}",
+                )
+        else:
+            # No roles means no inventory usage
+            output += """## Usage via Inventory
+
+**This module cannot be used via the inventory interface.**
+"""
+
+        ##### Print usage via Nix / nixos #####
+        if not isinstance(options_file, str):
+            print(
+                f"Skipping {module_name}: Cannot be used via import clanModules.{module_name}"
+            )
+            output += """## Usage via Nix
+
+**This module cannot be imported directly in your nixos configuration.**
+
+"""
+        else:
+            output += module_nix_usage(module_name)
+            no_options = "** This module doesnt require any options to be set.**"
+            output += print_options(options_file, options_head, no_options)
+
+        outfile = Path(OUT) / f"clanModules/{module_name}.md"
+        outfile.parent.mkdir(
+            parents=True,
+            exist_ok=True,
+        )
+        with outfile.open("w") as of:
+            of.write(output)
+
+    modules_index += "</div>"
+    modules_index += "\n"
+    modules_outfile = Path(OUT) / "clanModules/index.md"
+
+    with modules_outfile.open("w") as of:
+        of.write(modules_index)
+
+
+def build_option_card(module_name: str, frontmatter: Frontmatter) -> str:
+    """
+    Build the overview index card for each reference target option.
+    """
+
+    def indent_all(text: str, indent_size: int = 4) -> str:
+        """
+        Indent all lines in a string.
+        """
+        indent = " " * indent_size
+        lines = text.split("\n")
+        indented_text = indent + ("\n" + indent).join(lines)
+        return indented_text
+
+    def to_md_li(module_name: str, frontmatter: Frontmatter) -> str:
+        md_li = (
+            f"""-   **[{module_name}](./{"-".join(module_name.split(" "))}.md)**\n\n"""
+        )
+        md_li += f"""{indent_all("---", 4)}\n\n"""
+        fmd = f"\n{frontmatter.description.strip()}" if frontmatter.description else ""
+        md_li += f"""{indent_all(fmd, 4)}"""
+        return md_li
+
+    return f"{to_md_li(module_name, frontmatter)}\n\n"
+
+
 def split_options_by_root(options: dict[str, Any]) -> dict[str, dict[str, Any]]:
-    """Split the flat dictionary of options into a dict of which each entry will construct complete option trees.
+    """
+    Split the flat dictionary of options into a dict of which each entry will construct complete option trees.
     {
         "a": { Data }
         "a.b": { Data }
@@ -461,7 +765,9 @@ def option_short_name(option_name: str) -> str:
 
 
 def options_to_tree(options: dict[str, Any], debug: bool = False) -> Option:
-    """Convert the options dictionary to a tree structure."""
+    """
+    Convert the options dictionary to a tree structure.
+    """
 
     # Helper function to create nested structure
     def add_to_tree(path_parts: list[str], info: Any, current_node: Option) -> None:
@@ -513,24 +819,22 @@ def options_to_tree(options: dict[str, Any], debug: bool = False) -> Option:
 
 
 def options_docs_from_tree(
-    root: Option,
-    init_level: int = 1,
-    prefix: list[str] | None = None,
+    root: Option, init_level: int = 1, prefix: list[str] | None = None
 ) -> str:
-    """Eender the options from the tree structure.
+    """
+    eender the options from the tree structure.
 
     Args:
     root (Option): The root option node.
     init_level (int): The initial level of indentation.
     prefix (list str): Will be printed as common prefix of all attribute names.
-
     """
 
     def render_tree(option: Option, level: int = init_level) -> str:
         output = ""
 
         should_render = not option.name.startswith("<") and not option.name.startswith(
-            "_",
+            "_"
         )
         if should_render:
             # short_name = option_short_name(option.name)
@@ -555,8 +859,12 @@ def options_docs_from_tree(
     return md
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  #
     produce_clan_core_docs()
 
     produce_clan_service_author_docs()
+
+    # produce_clan_modules_docs()
     produce_clan_service_docs()
+
+    # produce_clan_modules_frontmatter_docs()

docs/site/api.md

@@ -1,10 +1,7 @@
-______________________________________________________________________
-
-template: options.html hide:
-
-- navigation
-- toc
-
-______________________________________________________________________
-
-<redoc src="/openapi.json" />
+---
+template: options.html
+hide:
+  - navigation
+  - toc
+---
+<redoc src="/openapi.json" />

docs/site/concepts/autoincludes.md

@@ -1,35 +1,15 @@
-# Auto-included Files
 
-Clan automatically imports specific files from each machine directory and
-registers them, reducing the need for manual configuration.
+Clan automatically imports the following files from a directory and registers them.
 
-## Machine Registration
+## Machine registration
 
-Every folder under `machines/{machineName}` is automatically registered as a
-Clan machine.
+Every folder `machines/{machineName}` will be registered automatically as a Clan machine.
 
-!!! info "Files loaded automatically for each machine"
+!!! info "Automatically loaded files"
 
-The following files are detected and imported for every Clan machine:
+    The following files are loaded automatically for each Clan machine:
 
-- [x] `machines/{machineName}/configuration.nix` Main configuration file for the
-  machine.
-
-- [x] `machines/{machineName}/hardware-configuration.nix` Hardware-specific
-  configuration generated by NixOS.
-
-- [x] `machines/{machineName}/facter.json` Contains system facts. Automatically
-  generated — see [nixos-facter](https://clan.lol/blog/nixos-facter/) for
-  details.
-
-- [x] `machines/{machineName}/disko.nix` Disk layout configuration. See the
-  [disko quickstart](https://github.com/nix-community/disko/blob/master/docs/quickstart.md)
-  for more info.
-
-## Other Auto-included Files
-
-- **`inventory.json`** Managed by Clan's API. Merges with `clan.inventory` to
-  extend the inventory.
-
-- **`.clan-flake`** Sentinel file to be used to locate the root of a Clan
-  repository. Falls back to `.git`, `.hg`, `.svn`, or `flake.nix` if not found.
+    - [x] `machines/{machineName}/configuration.nix`
+    - [x] `machines/{machineName}/hardware-configuration.nix`
+    - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/)
+    - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md).

docs/site/concepts/generators.md

@@ -1,21 +1,14 @@
 # Generators
 
-Defining a linux user's password via the nixos configuration previously required
-running `mkpasswd ...` and then copying the hash back into the nix
-configuration.
+Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration.
 
-In this example, we will guide you through automating that interaction using
-clan `vars`.
+In this example, we will guide you through automating that interaction using clan `vars`.
 
-For a more general explanation of what clan vars are and how it works, see the
-intro of the [Reference Documentation for vars](../reference/clan.core/vars.md)
+For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](../reference/clan.core/vars.md)
 
 This guide assumes
-
-- Clan is set up already (see
-  [Getting Started](../guides/getting-started/index.md))
-- a machine has been added to the clan (see
-  [Adding Machines](../guides/getting-started/add-machines.md))
+- Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
+- a machine has been added to the clan (see [Adding Machines](../guides/getting-started/add-machines.md))
 
 This section will walk you through the following steps:
 
@@ -36,9 +29,7 @@ In this example, a `vars` `generator` is used to:
 - store the hash in a file
 - expose the file path to the nixos configuration
 
-Create a new nix file `root-password.nix` with the following content and import
-it into your `configuration.nix`
-
+Create a new nix file `root-password.nix` with the following content and import it into your `configuration.nix`
 ```nix
 {config, pkgs, ...}: {
 
@@ -71,29 +62,24 @@ it into your `configuration.nix`
 ## Inspect the status
 
 Executing `clan vars list`, you should see the following:
-
 ```shellSession
 $ clan vars list my_machine
 root-password/password-hash: <not set>
 ```
 
-...indicating that the value `password-hash` for the generator `root-password`
-is not set yet.
+...indicating that the value `password-hash` for the generator `root-password` is not set yet.
 
 ## Generate the values
 
-This step is not strictly necessary, as deploying the machine via
-`clan machines update` would trigger the generator as well.
+This step is not strictly necessary, as deploying the machine via `clan machines update` would trigger the generator as well.
 
 To run the generator, execute `clan vars generate` for your machine
-
 ```shellSession
 $ clan vars generate my_machine
 Enter the value for root-password/password-input (hidden):
 ```
 
 After entering the value, the updated status is reported:
-
 ```shellSession
 Updated var root-password/password-hash
   old: <not set>
@@ -106,7 +92,6 @@ With the last step, a new file was created in your repository:
 `vars/per-machine/my-machine/root-password/password-hash/value`
 
 If the repository is a git repository, a commit was created automatically:
-
 ```shellSession
 $ git log -n1
 commit ... (HEAD -> master)
@@ -124,13 +109,9 @@ clan machines update my_machine
 
 ## Share root password between machines
 
-If we just imported the `root-password.nix` from above into more machines, clan
-would ask for a new password for each additional machine.
-
-If the root password instead should only be entered once and shared across all
-machines, the generator defined above needs to be declared as `shared`, by
-adding `share = true` to it:
+If we just imported the `root-password.nix` from above into more machines, clan would ask for a new password for each additional machine.
 
+If the root password instead should only be entered once and shared across all machines, the generator defined above needs to be declared as `shared`, by adding `share = true` to it:
 ```nix
 {config, pkgs, ...}: {
   clan.vars.generators.root-password = {
@@ -140,15 +121,13 @@ adding `share = true` to it:
 }
 ```
 
-Importing that shared generator into each machine, will ensure that the password
-is only asked once the first machine gets updated and then re-used for all
-subsequent machines.
+Importing that shared generator into each machine, will ensure that the password is only asked once the first machine gets updated and then re-used for all subsequent machines.
 
 ## Change the root password
 
-Changing the password can be done via this command. Replace `my-machine` with
-your machine. If the password is shared, just pick any machine that has the
-generator declared.
+Changing the password can be done via this command.
+Replace `my-machine` with your machine.
+If the password is shared, just pick any machine that has the generator declared.
 
 ```shellSession
 $ clan vars generate my-machine --generator root-password --regenerate
@@ -162,6 +141,7 @@ Updated var root-password/password-hash
   new: $6$OyoQtDVzeemgh8EQ$zRK...
 ```
 
+
 ## Further Reading
 
 - [Reference Documentation for `clan.core.vars` NixOS options](../reference/clan.core/vars.md)

docs/site/concepts/inventory.md

@@ -1,79 +1,62 @@
-`Inventory` is an abstract service layer for consistently configuring
-distributed services across machine boundaries.
+
+`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
 
 ## Concept
 
-Its concept is slightly different to what NixOS veterans might be used to. The
-inventory is a service definition on a higher level, not a machine
-configuration. This allows you to define a consistent and coherent service.
+Its concept is slightly different to what NixOS veterans might be used to. The inventory is a service definition on a higher level, not a machine configuration. This allows you to define a consistent and coherent service.
 
-The inventory logic will automatically derive the modules and configurations to
-enable on each machine in your `clan` based on its `role`. This makes it super
-easy to setup distributed `services` such as Backups, Networking, traditional
-cloud services, or peer-to-peer based applications.
+The inventory logic will automatically derive the modules and configurations to enable on each machine in your `clan` based on its `role`. This makes it super easy to setup distributed `services` such as Backups, Networking, traditional cloud services, or peer-to-peer based applications.
 
-The following tutorial will walk through setting up a Backup service where the
-terms `Service` and `Role` will become more clear.
+The following tutorial will walk through setting up a Backup service where the terms `Service` and `Role` will become more clear.
 
-!!! example "Experimental status" The inventory implementation is not considered
-stable yet. We are actively soliciting feedback from users.
+!!! example "Experimental status"
+    The inventory implementation is not considered stable yet.
+    We are actively soliciting feedback from users.
 
-```
-Stabilizing the API is a priority.
-```
+    Stabilizing the API is a priority.
 
 ## Prerequisites
 
-- [x] [Add some machines](../guides/getting-started/add-machines.md) to your
-  Clan.
+- [x] [Add some machines](../guides/getting-started/add-machines.md) to your Clan.
 
 ## Services
 
-The inventory defines `services`. Membership of `machines` is defined via
-`roles` exclusively.
+The inventory defines `services`. Membership of `machines` is defined via `roles` exclusively.
 
-See each [modules documentation](../reference/clanServices/index.md) for its
-available roles.
+See each [modules documentation](../reference/clanServices/index.md) for its available roles.
 
 ### Adding services to machines
 
-A service can be added to one or multiple machines via `Roles`. Clan's `Role`
-interface provide sane defaults for a module this allows the module author to
-reduce the configuration overhead to a minimum.
+A service can be added to one or multiple machines via `Roles`. Clan's `Role` interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
 
-Each service can still be customized and configured according to the modules
-options.
+Each service can still be customized and configured according to the modules options.
 
 - Per instance configuration via `services.<serviceName>.<instanceName>.config`
-- Per role configuration via
-  `services.<serviceName>.<instanceName>.roles.<roleName>.config`
-- Per machine configuration via
-  `services.<serviceName>.<instanceName>.machines.<machineName>.config`
+- Per role configuration via `services.<serviceName>.<instanceName>.roles.<roleName>.config`
+- Per machine configuration via `services.<serviceName>.<instanceName>.machines.<machineName>.config`
 
 ### Setting up the Backup Service
 
 !!! Example "Borgbackup Example"
 
-````
-To configure a service it needs to be added to the machine.
-It is required to assign the service (`borgbackup`) an arbitrary instance name. (`instance_1`)
+    To configure a service it needs to be added to the machine.
+    It is required to assign the service (`borgbackup`) an arbitrary instance name. (`instance_1`)
 
-See also: [Multiple Service Instances](#multiple-service-instances)
+    See also: [Multiple Service Instances](#multiple-service-instances)
 
-```{.nix hl_lines="6-7"}
-clan-core.lib.clan {
-    inventory = {
-        services = {
-            borgbackup.instance_1 = {
-                # Machines can be added here.
-                roles.client.machines = [ "jon" ];
-                roles.server.machines = [ "backup_server" ];
+    ```{.nix hl_lines="6-7"}
+    clan-core.lib.clan {
+        inventory = {
+            services = {
+                borgbackup.instance_1 = {
+                    # Machines can be added here.
+                    roles.client.machines = [ "jon" ];
+                    roles.server.machines = [ "backup_server" ];
+                };
             };
         };
-    };
-}
-```
-````
+    }
+    ```
 
 ### Scaling the Backup
 
@@ -83,60 +66,56 @@ It is possible to add services to multiple machines via tags as shown
 
 !!! Example "Tags Example"
 
-````
-```{.nix hl_lines="5 8 14"}
-clan-core.lib.clan {
-    inventory = {
-        machines = {
-            "jon" = {
-                tags = [ "backup" ];
+    ```{.nix hl_lines="5 8 14"}
+    clan-core.lib.clan {
+        inventory = {
+            machines = {
+                "jon" = {
+                    tags = [ "backup" ];
+                };
+                "sara" = {
+                    tags = [ "backup" ];
+                };
+                # ...
             };
-            "sara" = {
-                tags = [ "backup" ];
-            };
-            # ...
-        };
-        services = {
-            borgbackup.instance_1 = {
-                roles.client.tags = [ "backup" ];
-                roles.server.machines = [ "backup_server" ];
+            services = {
+                borgbackup.instance_1 = {
+                    roles.client.tags = [ "backup" ];
+                    roles.server.machines = [ "backup_server" ];
+                };
             };
         };
-    };
-}
-```
-````
+    }
+    ```
 
 ### Multiple Service Instances
 
-!!! danger "Important" Not all modules implement support for multiple instances
-yet. Multiple instance usage could create complexity, refer to each modules
-documentation, for intended usage.
+!!! danger "Important"
+    Not all modules implement support for multiple instances yet.
+    Multiple instance usage could create complexity, refer to each modules documentation, for intended usage.
 
 !!! Example
 
-````
-In this example `backup_server` has role `client` and `server` in different instances.
+    In this example `backup_server` has role `client` and `server` in different instances.
 
-```{.nix hl_lines="11 14"}
-clan-core.lib.clan {
-    inventory = {
-        machines = {
-            "jon" = {};
-            "backup_server" = {};
-            "backup_backup_server" = {}
-        };
-        services = {
-            borgbackup.instance_1 = {
-                roles.client.machines = [ "jon" ];
-                roles.server.machines = [ "backup_server" ];
+    ```{.nix hl_lines="11 14"}
+    clan-core.lib.clan {
+        inventory = {
+            machines = {
+                "jon" = {};
+                "backup_server" = {};
+                "backup_backup_server" = {}
             };
-            borgbackup.instance_2 = {
-                roles.client.machines = [ "backup_server" ];
-                roles.server.machines = [ "backup_backup_server" ];
+            services = {
+                borgbackup.instance_1 = {
+                    roles.client.machines = [ "jon" ];
+                    roles.server.machines = [ "backup_server" ];
+                };
+                borgbackup.instance_2 = {
+                    roles.client.machines = [ "backup_server" ];
+                    roles.server.machines = [ "backup_backup_server" ];
+                };
             };
         };
-    };
-}
-```
-````
+    }
+    ```

docs/site/concepts/templates.md

@@ -1,8 +1,7 @@
 # How Templates work
 
-Clan offers the ability to use templates for creating different resources. It
-comes with some `<builtin>` templates and discovers all exposed templates from
-its flake's `inputs`
+Clan offers the ability to use templates for creating different resources.
+It comes with some `<builtin>` templates and discovers all exposed templates from its flake's `inputs`
 
 For example one can list all current templates like this:
 
@@ -39,8 +38,7 @@ Available 'machine' templates
 
 Templates are referenced via the `--template` `selector`
 
-clan-core ships its native/builtin templates. Those are referenced if the
-selector is a plain string ( without `#` or `./.` )
+clan-core ships its native/builtin templates. Those are referenced if the selector is a plain string ( without `#` or `./.` )
 
 For example:
 
@@ -50,14 +48,11 @@ would use the native `<builtin>.flake-parts` template
 
 ## Selectors follow nix flake `reference#attribute` syntax
 
-Selectors follow a very similar pattern as Nix's native attribute selection
-behavior.
+Selectors follow a very similar pattern as Nix's native attribute selection behavior.
 
-Just like `nix build .` would build `packages.x86-linux.default` of the flake in
-`./.`
+Just like `nix build .` would build `packages.x86-linux.default` of the flake in `./.`
 
-`clan flakes create --template=.` would create a clan from your **local**
-`default` clan template (`templates.clan.default`).
+`clan flakes create --template=.` would create a clan from your **local** `default` clan template (`templates.clan.default`).
 
 In fact this command would be equivalent, just make it more explicit
 
@@ -65,11 +60,10 @@ In fact this command would be equivalent, just make it more explicit
 
 ## Remote templates
 
-Just like with Nix you could specify a remote url or path to the flake
-containing the template
+Just like with Nix you could specify a remote url or path to the flake containing the template
 
 `clan flakes create --template=github:owner/repo#foo`
 
-!!! Note "Implementation Note" Not all features of Nix's attribute selection are
-currently matched. There are minor differences in case of unexpected behavior
-please create an [issue](https://git.clan.lol/clan/clan-core/issues/new)
+!!! Note "Implementation Note"
+    Not all features of Nix's attribute selection are currently matched.
+    There are minor differences in case of unexpected behavior please create an [issue](https://git.clan.lol/clan/clan-core/issues/new)

docs/site/decisions/01-ClanModules.md

@@ -13,20 +13,15 @@ To define a service in Clan, you need to define two things:
 - `clanModule` - defined by module authors
 - `inventory` - defined by users
 
-The `clanModule` is currently a plain NixOS module. It is conditionally imported
-into each machine depending on the `service` and `role`.
+The `clanModule` is currently a plain NixOS module. It is conditionally imported into each machine depending on the `service` and `role`.
 
-A `role` is a function of a machine within a service. For example in the
-`backup` service there are `client` and `server` roles.
+A `role` is a function of a machine within a service. For example in the `backup` service there are `client` and `server` roles.
 
-The `inventory` contains the settings for the user/consumer of the module. It
-describes what `services` run on each machine and with which `roles`.
+The `inventory` contains the settings for the user/consumer of the module. It describes what `services` run on each machine and with which `roles`.
 
 Additionally any `service` can be instantiated multiple times.
 
-This ADR proposes that we change how to write a `clanModule`. The `inventory`
-should get a new attribute called `instances` that allow for configuration of
-these modules.
+This ADR proposes that we change how to write a `clanModule`. The `inventory` should get a new attribute called `instances` that allow for configuration of these modules.
 
 ### Status Quo
 
@@ -71,144 +66,103 @@ in {
 
 Problems with the current way of writing clanModules:
 
-1. No way to retrieve the config of a single service instance, together with its
-   name.
+1. No way to retrieve the config of a single service instance, together with its name.
+2. Directly exporting a single, anonymous nixosModule without any intermediary attribute layers doesn't leave room for exporting other inventory resources such as potentially `vars` or `homeManagerConfig`.
+3. Can't access multiple config instances individually.
+    Example:
+    ```nix
+    inventory = {
+      services = {
+        network.c-base = {
+          instanceConfig.ips = {
+            mors = "172.139.0.2";
+          };
+        };
+        network.gg23 = {
+          instanceConfig.ips = {
+            mors = "10.23.0.2";
+          };
+        };
+      };
+    };
+    ```
+   This doesn't work because all instance configs are applied to the same namespace. So this results in a conflict currently.
+   Resolving this problem means that new inventory modules cannot be plain nixos modules anymore. If they are configured via `instances` / `instanceConfig` they cannot be configured without using the inventory. (There might be ways to inject instanceConfig but that requires knowledge of inventory internals)
 
-2. Directly exporting a single, anonymous nixosModule without any intermediary
-   attribute layers doesn't leave room for exporting other inventory resources
-   such as potentially `vars` or `homeManagerConfig`.
+4. Writing modules for multiple instances is cumbersome. Currently the clanModule author has to write one or multiple `fold` operations for potentially every nixos option to define how multiple service instances merge into every single one option. The new idea behind this adr is to pull the common fold function into the outer context provide it as a common helper. (See the example below. `perInstance` analog to the well known `perSystem` of flake-parts)
 
-3. Can't access multiple config instances individually. Example:
+5. Each role has a different interface. We need to render that interface into json-schema which includes creating an unnecessary test machine currently. Defining the interface at a higher level (outside of any machine context) allows faster evaluation and an isolation by design from any machine.
+This allows rendering the UI (options tree) of a service by just knowing the service and the corresponding roles without creating a dummy machine.
 
-   ```nix
-   inventory = {
-     services = {
-       network.c-base = {
-         instanceConfig.ips = {
-           mors = "172.139.0.2";
-         };
-       };
-       network.gg23 = {
-         instanceConfig.ips = {
-           mors = "10.23.0.2";
-         };
-       };
-     };
-   };
-   ```
-
-   This doesn't work because all instance configs are applied to the same
-   namespace. So this results in a conflict currently. Resolving this problem
-   means that new inventory modules cannot be plain nixos modules anymore. If
-   they are configured via `instances` / `instanceConfig` they cannot be
-   configured without using the inventory. (There might be ways to inject
-   instanceConfig but that requires knowledge of inventory internals)
-
-4. Writing modules for multiple instances is cumbersome. Currently the
-   clanModule author has to write one or multiple `fold` operations for
-   potentially every nixos option to define how multiple service instances merge
-   into every single one option. The new idea behind this adr is to pull the
-   common fold function into the outer context provide it as a common helper.
-   (See the example below. `perInstance` analog to the well known `perSystem` of
-   flake-parts)
-
-5. Each role has a different interface. We need to render that interface into
-   json-schema which includes creating an unnecessary test machine currently.
-   Defining the interface at a higher level (outside of any machine context)
-   allows faster evaluation and an isolation by design from any machine. This
-   allows rendering the UI (options tree) of a service by just knowing the
-   service and the corresponding roles without creating a dummy machine.
-
-6. The interface of defining config is wrong. It is possible to define config
-   that applies to multiple machine at once. It is possible to define config
-   that applies to a machine as a hole. But this is wrong behavior because the
-   options exist at the role level. So config must also always exist at the role
-   level. Currently we merge options and config together but that may produce
-   conflicts. Those module system conflicts are very hard to foresee since they
-   depend on what roles exist at runtime.
+6. The interface of defining config is wrong. It is possible to define config that applies to multiple machine at once. It is possible to define config that applies to
+a machine as a hole. But this is wrong behavior because the options exist at the role level. So config must also always exist at the role level.
+Currently we merge options and config together but that may produce conflicts. Those module system conflicts are very hard to foresee since they depend on what roles exist at runtime.
 
 ## Proposed Change
 
-We will create a new module class which is defined by `_class = "clan.service"`
-([documented here](https://nixos.org/manual/nixpkgs/stable/#module-system-lib-evalModules-param-class)).
+We will create a new module class which is defined by `_class = "clan.service"` ([documented here](https://nixos.org/manual/nixpkgs/stable/#module-system-lib-evalModules-param-class)).
 
-Existing clan modules will still work by continuing to be plain NixOS modules.
-All new modules can set `_class = "clan.service";` to use the proposed features.
+Existing clan modules will still work by continuing to be plain NixOS modules. All new modules can set `_class = "clan.service";` to use the proposed features.
 
-In short the change introduces a new module class that makes the currently
-necessary folding of `clan.service`s `instances` and `roles` a common operation.
-The module author can define the inner function of the fold operations which is
-called a `clan.service` module.
+In short the change introduces a new module class that makes the currently necessary folding of `clan.service`s `instances` and `roles` a common operation. The module author can define the inner function of the fold operations which is called a `clan.service` module.
 
 There are the following attributes of such a module:
 
 ### `roles.<roleName>.interface`
 
-Each role can have a different interface for how to be configured. I.e.: A
-`client` role might have different options than a `server` role.
+Each role can have a different interface for how to be configured.
+I.e.: A `client` role might have different options than a `server` role.
 
 This attribute should be used to define `options`. (Not `config` !)
 
 The end-user defines the corresponding `config`.
 
-This submodule will be evaluated for each `instance role` combination and passed
-as argument into `perInstance`.
+This submodule will be evaluated for each `instance role` combination and passed as argument into `perInstance`.
 
-This submodules `options` will be evaluated to build the UI for that module
-dynamically.
+This submodules `options` will be evaluated to build the UI for that module dynamically.
 
 ### **Result attributes**
 
-Some common result attributes are produced by modules of this proposal, those
-will be referenced later in this document but are commonly defined as:
+Some common result attributes are produced by modules of this proposal, those will be referenced later in this document but are commonly defined as:
 
-- `nixosModule` A single nixos module.
-  (`{config, ...}:{ environment.systemPackages = []; }`)
-- `services.<serviceName>` An attribute set of `_class = clan.service`. Which
-  contain the same thing as this whole ADR proposes.
+- `nixosModule` A single nixos module. (`{config, ...}:{ environment.systemPackages = []; }`)
+- `services.<serviceName>` An attribute set of `_class = clan.service`. Which contain the same thing as this whole ADR proposes.
 - `vars` To be defined. Reserved for now.
 
 ### `roles.<roleName>.perInstance`
 
-This acts like a function that maps over all `service instances` of a given
-`role`. It produces the previously defined **result attributes**.
+This acts like a function that maps over all `service instances` of a given `role`.
+It produces the previously defined **result attributes**.
 
-I.e. This allows to produce multiple `nixosModules` one for every instance of
-the service. Hence making multiple `service instances` convenient by leveraging
-the module-system merge behavior.
+I.e. This allows to produce multiple `nixosModules` one for every instance of the service.
+Hence making multiple `service instances` convenient by leveraging the module-system merge behavior.
 
 ### `perMachine`
 
-This acts like a function that maps over all `machines` of a given `service`. It
-produces the previously defined **result attributes**.
+This acts like a function that maps over all `machines` of a given `service`.
+It produces the previously defined **result attributes**.
 
-I.e. this allows to produce exactly one `nixosModule` per `service`. Making it
-easy to set nixos-options only once if they have a one-to-one relation to a
-service being enabled.
+I.e. this allows to produce exactly one `nixosModule` per `service`.
+Making it easy to set nixos-options only once if they have a one-to-one relation to a service being enabled.
 
 Note: `lib.mkIf` can be used on i.e. `roleName` to make the scope more specific.
 
 ### `services.<serviceName>`
 
-This allows to define nested services. i.e the *service* `backup` might define a
-nested *service* `ssh` which sets up an ssh connection.
+This allows to define nested services.
+i.e the *service* `backup` might define a nested *service* `ssh` which sets up an ssh connection.
 
 This can be defined in `perMachine` and `perInstance`
 
 - For Every `instance` a given `service` may add multiple nested `services`.
-- A given `service` may add a static set of nested `services`; Even if there are
-  multiple instances of the same given service.
+- A given `service` may add a static set of nested `services`; Even if there are multiple instances of the same given service.
 
-Q: Why is this not a top-level attribute? A: Because nested service definitions
-may also depend on a `role` which must be resolved depending on `machine` and
-`instance`. The top-level module doesn't know anything about machines. Keeping
-the service layer machine agnostic allows us to build the UI for a module
-without adding any machines. (One of the problems with the current system)
+Q: Why is this not a top-level attribute?
+A: Because nested service definitions may also depend on a `role` which must be resolved depending on `machine` and `instance`. The top-level module doesn't know anything about machines. Keeping the service layer machine agnostic allows us to build the UI for a module without adding any machines. (One of the problems with the current system)
 
 ```
 zerotier/default.nix
 ```
-
 ```nix
 # Some example module
 {
@@ -267,25 +221,15 @@ zerotier/default.nix
 
 ## Inventory.instances
 
-This document also proposes to add a new attribute to the inventory that allow
-for exclusive configuration of the new modules. This allows to better separate
-the new and the old way of writing and configuring modules. Keeping the new
-implementation more focussed and keeping existing technical debt out from the
-beginning.
+This document also proposes to add a new attribute to the inventory that allow for exclusive configuration of the new modules.
+This allows to better separate the new and the old way of writing and configuring modules. Keeping the new implementation more focussed and keeping existing technical debt out from the beginning.
 
 The following thoughts went into this:
 
-- Getting rid of `<serviceName>`: Using only the attribute name (plain string)
-  is not sufficient for defining the source of the service module. Encoding meta
-  information into it would also require some extensible format specification
-  and parser.
-- removing instanceConfig and machineConfig: There is no such config. Service
-  configuration must always be role specific, because the options are defined on
-  the role.
-- renaming `config` to `settings` or similar. Since `config` is a module system
-  internal name.
-- Tags and machines should be an attribute set to allow setting `settings` on
-  that level instead.
+- Getting rid of `<serviceName>`: Using only the attribute name (plain string) is not sufficient for defining the source of the service module. Encoding meta information into it would also require some extensible format specification and parser.
+- removing instanceConfig and machineConfig: There is no such config. Service configuration must always be role specific, because the options are defined on the role.
+- renaming `config` to `settings` or similar. Since `config` is a module system internal name.
+- Tags and machines should be an attribute set to allow setting `settings` on that level instead.
 
 ```nix
 {
@@ -314,9 +258,7 @@ The following thoughts went into this:
 
 ## Iteration note
 
-We want to implement the system as described. Once we have sufficient data on
-real world use-cases and modules we might revisit this document along with the
-updated implementation.
+We want to implement the system as described. Once we have sufficient data on real world use-cases and modules we might revisit this document along with the updated implementation.
 
 ## Real world example
 

docs/site/decisions/02-clan-api.md

@@ -6,8 +6,7 @@ Accepted
 
 ## Context
 
-In the long term we envision the clan application will consist of the following
-user facing tools in the long term.
+In the long term we envision the clan application will consist of the following user facing tools in the long term.
 
 - `CLI`
 - `TUI`
@@ -15,20 +14,17 @@ user facing tools in the long term.
 - `REST-API`
 - `Mobile Application`
 
-We might not be sure whether all of those will exist but the architecture should
-be generic such that those are possible without major changes of the underlying
-system.
+We might not be sure whether all of those will exist but the architecture should be generic such that those are possible without major changes of the underlying system.
 
 ## Decision
 
 This leads to the conclusion that we should do `library` centric development.
-With the current `clan` python code being a library that can be imported to
-create various tools ontop of it. All **CLI** or **UI** related parts should be
-moved out of the main library.
+With the current `clan` python code being a library that can be imported to create various tools ontop of it.
+All **CLI** or **UI** related parts should be moved out of the main library.
 
 Imagine roughly the following architecture:
 
-```mermaid
+``` mermaid
 graph TD
   %% Define styles
   classDef frontend fill:#f9f,stroke:#333,stroke-width:2px;
@@ -70,18 +66,14 @@ graph TD
   BusinessLogic --> NIX
 ```
 
-With this very simple design it is ensured that all the basic features remain
-stable across all frontends. In the end it is straight forward to create python
-library function calls in a testing framework to ensure that kind of stability.
+With this very simple design it is ensured that all the basic features remain stable across all frontends.
+In the end it is straight forward to create python library function calls in a testing framework to ensure that kind of stability.
 
-Integration tests and smaller unit-tests should both be utilized to ensure the
-stability of the library.
+Integration tests and smaller unit-tests should both be utilized to ensure the stability of the library.
 
 Note: Library function don't have to be json-serializable in general.
 
-Persistence includes but is not limited to: creating git commits, writing to
-inventory.json, reading and writing vars, and interacting with persisted data in
-general.
+Persistence includes but is not limited to: creating git commits, writing to inventory.json, reading and writing vars, and interacting with persisted data in general.
 
 ## Benefits / Drawbacks
 
@@ -89,51 +81,34 @@ general.
 - (+) Consistency and inherent behavior
 - (+) Performance & Scalability
 - (+) Different frontends for different user groups
-- (+) Documentation per library function makes it convenient to interact with
-  the clan resources.
-- (+) Testing the library ensures stability of the underlyings for all layers
-  above.
+- (+) Documentation per library function makes it convenient to interact with the clan resources.
+- (+) Testing the library ensures stability of the underlyings for all layers above.
 - (-) Complexity overhead
 - (-) library needs to be designed / documented
 - (+) library can be well documented since it is a finite set of functions.
 - (-) Error handling might be harder.
 - (+) Common error reporting
-- (-) different frontends need different features. The library must include them
-  all.
+- (-) different frontends need different features. The library must include them all.
 - (+) All those core features must be implemented anyways.
-- (+) VPN Benchmarking uses the existing library's already and works relatively
-  well.
+- (+) VPN Benchmarking uses the existing library's already and works relatively well.
 
 ## Implementation considerations
 
-Not all required details that need to change over time are possible to be
-pointed out ahead of time. The goal of this document is to create a common
-understanding for how we like our project to be structured. Any future commits
-should contribute to this goal.
+Not all required details that need to change over time are possible to be pointed out ahead of time.
+The goal of this document is to create a common understanding for how we like our project to be structured.
+Any future commits should contribute to this goal.
 
 Some ideas what might be needed to change:
 
 - Having separate locations or packages for the library and the CLI.
-- Rename the `clan_cli` package to `clan` and move the `cli` frontend into a
-  subfolder or a separate package.
-- Python Argparse or other cli related code should not exist in the `clan`
-  python library.
-- `__init__.py` should be very minimal. Only init the business logic models and
-  resources. Note that all `__init__.py` files all the way up in the module tree
-  are always executed as part of the python module import logic and thus should
-  be as small as possible. i.e. `from clan_cli.vars.generators import ...`
-  executes both `clan_cli/__init__.py` and `clan_cli/vars/__init__.py` if any of
-  those exist.
+- Rename the `clan_cli` package to `clan` and move the `cli` frontend into a subfolder or a separate package.
+- Python Argparse or other cli related code should not exist in the `clan` python library.
+- `__init__.py` should be very minimal. Only init the business logic models and resources. Note that all `__init__.py` files all the way up in the module tree are always executed as part of the python module import logic and thus should be as small as possible.
+  i.e. `from clan_cli.vars.generators import ...` executes both `clan_cli/__init__.py` and `clan_cli/vars/__init__.py` if any of those exist.
 - `api` folder doesn't make sense since the python library `clan` is the api.
-- Logic needed for the webui that performs json serialization and
-  deserialization will be some `json-adapter` folder or package.
-- Code for serializing dataclasses and typed dictionaries is needed for the
-  persistence layer. (i.e. for read-write of inventory.json)
-- The inventory-json is a backend resource, that is internal. Its logic includes
-  merging, unmerging and partial updates with considering nix values and their
-  priorities. Nobody should try to read or write to it directly. Instead there
-  will be library methods i.e. to add a `service` or to update/read/delete some
-  information from it.
-- Library functions should be carefully designed with suitable conventions for
-  writing good api's in mind. (i.e:
-  https://swagger.io/resources/articles/best-practices-in-api-design/)
+- Logic needed for the webui that performs json serialization and deserialization will be some `json-adapter` folder or package.
+- Code for serializing dataclasses and typed dictionaries is needed for the persistence layer. (i.e. for read-write of inventory.json)
+- The inventory-json is a backend resource, that is internal. Its logic includes merging, unmerging and partial updates with considering nix values and their priorities. Nobody should try to read or write to it directly.
+  Instead there will be library methods i.e. to add a `service` or to update/read/delete some information from it.
+- Library functions should be carefully designed with suitable conventions for writing good api's in mind. (i.e: https://swagger.io/resources/articles/best-practices-in-api-design/)
+

docs/site/decisions/03-adr-numbering-process.md

@@ -6,39 +6,27 @@ Proposed after some conversation between @lassulus, @Mic92, & @lopter.
 
 ## Context
 
-It can be useful to refer to ADRs by their numbers, rather than their full
-title. To that end, short and sequential numbers are useful.
+It can be useful to refer to ADRs by their numbers, rather than their full title. To that end, short and sequential numbers are useful.
 
-The issue is that an ADR number is effectively assigned when the ADR is merged,
-before being merged its number is provisional. Because multiple ADRs can be
-written at the same time, you end-up with multiple provisional ADRs with the
-same number, for example this is the third ADR-3:
+The issue is that an ADR number is effectively assigned when the ADR is merged, before being merged its number is provisional. Because multiple ADRs can be written at the same time, you end-up with multiple provisional ADRs with the same number, for example this is the third ADR-3:
 
 1. ADR-3-clan-compat: see [#3212];
 2. ADR-3-fetching-nix-from-python: see [#3452];
 3. ADR-3-numbering-process: this ADR.
 
-This situation makes it impossible to refer to an ADR by its number, and why I
-(@lopter) went with the arbitrary number 7 in [#3196].
+This situation makes it impossible to refer to an ADR by its number, and why I (@lopter) went with the arbitrary number 7 in [#3196].
 
-We could solve this problem by using the PR number as the ADR number
-(@lassulus). The issue is that PR numbers are getting big in clan-core which
-does not make them easy to remember, or use in conversation and code (@lopter).
+We could solve this problem by using the PR number as the ADR number (@lassulus). The issue is that PR numbers are getting big in clan-core which does not make them easy to remember, or use in conversation and code (@lopter).
 
-Another approach would be to move the ADRs in a different repository, this would
-reset the counter back to 1, and make it straightforward to keep ADR and PR
-numbers in sync (@lopter). The issue then is that ADR are not in context with
-their changes which makes them more difficult to review (@Mic92).
+Another approach would be to move the ADRs in a different repository, this would reset the counter back to 1, and make it straightforward to keep ADR and PR numbers in sync (@lopter). The issue then is that ADR are not in context with their changes which makes them more difficult to review (@Mic92).
 
 ## Decision
 
 A third approach would be to:
 
-1. Commit ADRs before they are approved, so that the next ADR number gets
-   assigned;
-2. Open a PR for the proposed ADR;
-3. Update the ADR file committed in step 1, so that its markdown contents point
-   to the PR that tracks it.
+1. Commit ADRs before they are approved, so that the next ADR number gets assigned;
+1. Open a PR for the proposed ADR;
+1. Update the ADR file committed in step 1, so that its markdown contents point to the PR that tracks it.
 
 ## Consequences
 
@@ -48,13 +36,12 @@ This makes it easier to refer to them in conversation or in code.
 
 ### You need to have commit access to get an ADR number assigned
 
-This makes it more difficult for someone external to the project to contribute
-an ADR.
+This makes it more difficult for someone external to the project to contribute an ADR.
 
 ### Creating a new ADR requires multiple commits
 
 Maybe a script or CI flow could help with that if it becomes painful.
 
-[#3196]: https://git.clan.lol/clan/clan-core/pulls/3196/
 [#3212]: https://git.clan.lol/clan/clan-core/pulls/3212/
 [#3452]: https://git.clan.lol/clan/clan-core/pulls/3452/
+[#3196]: https://git.clan.lol/clan/clan-core/pulls/3196/

docs/site/decisions/04-fetching-nix-from-python.md

@@ -4,113 +4,83 @@ accepted
 
 ## Context
 
-In our clan-cli we need to get a lot of values from nix into the python runtime.
-This is used to determine the hostname, the target ips address, scripts to
-generate vars, file locations and many more.
+In our clan-cli we need to get a lot of values from nix into the python runtime. This is used to determine the hostname, the target ips address, scripts to generate vars, file locations and many more.
 
 Currently we use two different accessing methods:
 
 ### Method 1: deployment.json
 
-A json file that serializes some predefined values into a JSON file as
-build-time artifact.
+A json file that serializes some predefined values into a JSON file as build-time artifact.
 
 Downsides:
 
-- no access to flake level values
-- all or nothing:
-  - values are either cached via deployment.json or not. So we can only put
-    cheap values into there,
-  - in the past var generation script were added here, which added a huge build
-    time overhead for every time we wanted to do any action
-- duplicated nix code
-  - values need duplicated nix code, once to define them at the correct place in
-    the module system (clan.core.vars.generators) and code to accumulate them
-    again for the deployment.json (system.clan.deployment.data)
-  - This duality adds unnecessary dependencies to the nixos module system.
+* no access to flake level values
+* all or nothing:
+  * values are either cached via deployment.json or not. So we can only put cheap values into there,
+  * in the past var generation script were added here, which added a huge build time overhead for every time we wanted to do any action
+* duplicated nix code
+  * values need duplicated nix code, once to define them at the correct place in the module system (clan.core.vars.generators) and code to accumulate them again for the deployment.json (system.clan.deployment.data)
+  * This duality adds unnecessary dependencies to the nixos module system.
 
 Benefits:
 
-- Utilize `nix build` for caching the file.
-- Caching mechanism is very simple.
+* Utilize `nix build` for caching the file.
+* Caching mechanism is very simple.
+
 
 ### Method 2: Direct access
 
-Directly calling the evaluator / build sandbox via `nix build` and
-`nix eval`within the Python code
+Directly calling the evaluator / build sandbox via `nix build` and `nix eval`within the Python code
+
 
 Downsides:
 
-- Access is not cached: Static overhead (see below: ~1.5s) is present every
-  time, if we invoke `nix commands`
-  - The static overhead depends obviously which value we need to retrieve, since
-    the `evalModules` overhead depends, whether we evaluate some attribute
-    inside a machine or a flake attribute
-  - Accessing more and more attributes with this method increases the static
-    overhead, which leads to a linear decrease in performance.
-- Boilerplate for interacting with the CLI and Error handling code is repeated
-  every time.
+* Access is not cached: Static overhead (see below: \~1.5s) is present every time, if we invoke `nix commands`
+  * The static overhead depends obviously which value we need to retrieve, since the `evalModules` overhead depends, whether we evaluate some attribute inside a machine or a flake attribute
+  * Accessing more and more attributes with this method increases the static overhead, which leads to a linear decrease in performance.
+* Boilerplate for interacting with the CLI and Error handling code is repeated every time.
 
 Benefits:
 
-- Simple and native interaction with the `nix commands`is rather intuitive
-- Custom error handling for each attribute is easy
+* Simple and native interaction with the `nix commands`is rather intuitive
+* Custom error handling for each attribute is easy
 
-This sytem could be enhanced with custom nix expressions, which could be used in
-places where we don't want to put values into deployment.json or want to fetch
-flake level values. This also has some downsides:
+This sytem could be enhanced with custom nix expressions, which could be used in places where we don't want to put values into deployment.json or want to fetch flake level values. This also has some downsides:
 
-- technical debt
-  - we have to maintain custom nix expressions inside python code, embedding
-    code is error prone and the language linters won't help you here, so errors
-    are common and harder to debug.
-  - we need custom error reporting code in case something goes wrong, either the
-    value doesn't exist or there is an reported build error
-- no caching/custom caching logic
-  - currently there is no infrastructure to cache those extra values, so we
-    would need to store them somewhere, we could either enhance one of the many
-    classes we have or don't cache them at all
-  - even if we implement caching for extra nix expressions, there can be no
-    sharing between extra nix expressions. for example we have 2 nix
-    expressions, one fetches paths and values for all generators and the second
-    one fetches only the values, we still need to execute both of them in both
-    contexts although the second one could be skipped if the first one is
-    already cached
+* technical debt
+  * we have to maintain custom nix expressions inside python code, embedding code is error prone and the language linters won't help you here, so errors are common and harder to debug.
+  * we need custom error reporting code in case something goes wrong, either the value doesn't exist or there is an reported build error
+* no caching/custom caching logic
+  * currently there is no infrastructure to cache those extra values, so we would need to store them somewhere, we could either enhance one of the many classes we have or don't cache them at all
+  * even if we implement caching for extra nix expressions, there can be no sharing between extra nix expressions. for example we have 2 nix expressions, one fetches paths and values for all generators and the second one fetches only the values, we still need to execute both of them in both contexts although the second one could be skipped if the first one is already cached
 
 ### Method 3: nix select
 
 Move all code that extracts nix values into a common class:
 
 Downsides:
-
-- added complexity for maintaining our own DSL
+* added complexity for maintaining our own DSL
 
 Benefits:
+* we can implement an API (select DSL) to get those values from nix without writing complex nix expressions.
+* we can implement caching of those values beyond the runtime of the CLI
+* we can use precaching at different endpoints to eliminate most of multiple nix evaluations (except in cases where we have to break the cache or we don't know if we need the value in the value later and getting it is expensive).
+
 
-- we can implement an API (select DSL) to get those values from nix without
-  writing complex nix expressions.
-- we can implement caching of those values beyond the runtime of the CLI
-- we can use precaching at different endpoints to eliminate most of multiple nix
-  evaluations (except in cases where we have to break the cache or we don't know
-  if we need the value in the value later and getting it is expensive).
 
 ## Decision
 
 Use Method 3 (nix select) for extracting values out of nix.
 
-This adds the Flake class in flake.py with a select method, which takes a
-selector string and returns a python dict.
+This adds the Flake class in flake.py with a select method, which takes a selector string and returns a python dict.
 
 Example:
-
 ```python
 from clan_lib.flake import Flake
 flake = Flake("github:lassulus/superconfig")
 flake.select("nixosConfigurations.*.config.networking.hostName)
 ```
-
 returns:
-
 ```
 {
   "ignavia": "ignavia",
@@ -121,13 +91,7 @@ returns:
 
 ## Consequences
 
-- Faster execution due to caching most things beyond a single execution, if no
-  cache break happens execution is basically instant, because we don't need to
-  run nix again.
-- Better error reporting, since all nix values go through one chokepoint, we can
-  parse error messages in that chokepoint and report them in a more user
-  friendly way, for example if a value is missing at the expected location
-  inside the module system.
-- less embedded nix code inside python code
-- more portable CLI, since we need to import less modules into the module system
-  and most things can be extracted by the python code directly
+* Faster execution due to caching most things beyond a single execution, if no cache break happens execution is basically instant, because we don't need to run nix again.
+* Better error reporting, since all nix values go through one chokepoint, we can parse error messages in that chokepoint and report them in a more user friendly way, for example if a value is missing at the expected location inside the module system.
+* less embedded nix code inside python code
+* more portable CLI, since we need to import less modules into the module system and most things can be extracted by the python code directly

docs/site/decisions/05-deployment-parameters.md

@@ -6,16 +6,12 @@ accepted
 
 ## Context
 
-Currently different operations (install, update) have different modes. Install
-always evals locally and pushes the derivation to a remote system. update has a
-configurable buildHost and targetHost. Confusingly install always evals locally
-and update always evals on the targetHost, so hosts have different semantics in
-different operations contexts.
+Currently different operations (install, update) have different modes. Install always evals locally and pushes the derivation to a remote system. update has a configurable buildHost and targetHost.
+Confusingly install always evals locally and update always evals on the targetHost, so hosts have different semantics in different operations contexts.
 
 ## Decision
 
-Add evalHost to make this clear and configurable for the user. This would leave
-us with:
+Add evalHost to make this clear and configurable for the user. This would leave us with:
 
 - evalHost
 - buildHost
@@ -23,29 +19,18 @@ us with:
 
 for the update and install operation.
 
-`evalHost` would be the machine that evaluates the nixos configuration. if
-evalHost is not localhost, we upload the non secret vars and the nix archived
-flake (this is usually the same operation) to the evalMachine.
+`evalHost` would be the machine that evaluates the nixos configuration. if evalHost is not localhost, we upload the non secret vars and the nix archived flake (this is usually the same operation) to the evalMachine.
 
-`buildHost` would be what is used by the machine to build, it would correspond
-to `--build-host` on the nixos-rebuild command or `--builders` for nix build.
+`buildHost` would be what is used by the machine to build, it would correspond to `--build-host` on the nixos-rebuild command or `--builders` for nix build.
 
-`targetHost` would be the machine where the closure gets copied to and activated
-(either through install or switch-to-configuration). It corresponds to
-`--targetHost` for nixos-rebuild or where we usually point `nixos-anywhere` to.
+`targetHost` would be the machine where the closure gets copied to and activated (either through install or switch-to-configuration). It corresponds to `--targetHost` for nixos-rebuild or where we usually point `nixos-anywhere` to.
 
-This hosts could be set either through CLI args (or forms for the GUI) or via
-the inventory. If both are given, the CLI args would take precedence.
+This hosts could be set either through CLI args (or forms for the GUI) or via the inventory. If both are given, the CLI args would take precedence.
 
 ## Consequences
 
-We now support every deployment model of every tool out there with a bunch of
-simple flags. The semantics are more clear and we can write some nice
-documentation.
+We now support every deployment model of every tool out there with a bunch of simple flags. The semantics are more clear and we can write some nice documentation.
 
-The install code has to be reworked, since nixos-anywhere has problems with
-evalHost and targetHost being the same machine, So we would need to kexec first
-and use the kexec image (or installer) as the evalHost afterwards.
+The install code has to be reworked, since nixos-anywhere has problems with evalHost and targetHost being the same machine, So we would need to kexec first and use the kexec image (or installer) as the evalHost afterwards.
 
-In cases where the evalHost doesn't have access to the targetHost or buildHost,
-we need to setup temporary entries for the lifetime of the command.
+In cases where the evalHost doesn't have access to the targetHost or buildHost, we need to setup temporary entries for the lifetime of the command.

docs/site/decisions/README.md

@@ -1,15 +1,13 @@
 # Architecture Decision Records
 
-This section contains the architecture decisions that have been reviewed and
-generally agreed upon
+This section contains the architecture decisions that have been reviewed and generally agreed upon
 
 ## What is an ADR?
 
-> An architecture decision record (ADR) is a document that captures an important
-> architecture decision made along with its context and consequences.
+> An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences.
 
-!!! Note For further reading about adr's we recommend
-[architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record)
+!!! Note
+    For further reading about adr's we recommend [architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record)
 
 ## Crafting a new ADR
 

docs/site/decisions/_template.md

@@ -1,9 +1,7 @@
 # Decision record template by Michael Nygard
 
-This is the template in
-[Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
-You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the
-ADR files.
+This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files.
 
 In each ADR file, write these sections:
 
@@ -11,8 +9,7 @@ In each ADR file, write these sections:
 
 ## Status
 
-What is the status, such as proposed, accepted, rejected, deprecated,
-superseded, etc.?
+What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
 
 ## Context
 

docs/site/guides/age-plugins.md

@@ -1,14 +1,11 @@
 ## Using Age Plugins
 
-If you wish to use a key generated using an [age plugin] as your admin key,
-extra care is needed.
+If you wish to use a key generated using an [age plugin] as your admin key, extra care is needed.
 
-You must **precede your secret key with a comment that contains its
-corresponding recipient**.
+You must **precede your secret key with a comment that contains its corresponding recipient**.
 
-This is usually output as part of the generation process and is only required
-because there is no unified mechanism for recovering a recipient from a plugin
-secret key.
+This is usually output as part of the generation process
+and is only required because there is no unified mechanism for recovering a recipient from a plugin secret key.
 
 Here is an example:
 
@@ -17,16 +14,15 @@ Here is an example:
 AGE-PLUGIN-FIDO2-HMAC-1QQPQZRFR7ZZ2WCV...
 ```
 
-!!! note The comment that precedes the plugin secret key need only contain the
-recipient. Any other text is ignored.
+!!! note
+    The comment that precedes the plugin secret key need only contain the recipient.
+    Any other text is ignored.
 
-```
-In the example above, you can specify `# recipient: age1zdy...`, `# public: age1zdy....` or even
-just `# age1zdy....`
-```
+    In the example above, you can specify `# recipient: age1zdy...`, `# public: age1zdy....` or even
+    just `# age1zdy....`
 
-You will need to add an entry into your `flake.nix` to ensure that the necessary
-`age` plugins are loaded when using Clan:
+You will need to add an entry into your `flake.nix` to ensure that the necessary `age` plugins
+are loaded when using Clan:
 
 ```nix title="flake.nix"
 {

docs/site/guides/backups.md

@@ -1,3 +1,4 @@
+
 This guide explains how to set up and manage
 [BorgBackup](https://borgbackup.readthedocs.io/) for secure, efficient backups
 in a clan network. BorgBackup provides:
@@ -33,13 +34,11 @@ inventory.instances = {
 The input should be named according to your flake input. Jon is configured as a
 client machine with a destination pointing to a Hetzner Storage Box.
 
-To see a list of all possible options go to
-[borgbackup clan service](../reference/clanServices/borgbackup.md)
+To see a list of all possible options go to [borgbackup clan service](../reference/clanServices/borgbackup.md)
 
 ## Roles
 
-A Clan Service can have multiple roles, each role applies different nix config
-to the machine.
+A Clan Service can have multiple roles, each role applies different nix config to the machine.
 
 ### 1. Client
 
@@ -62,8 +61,8 @@ Destinations can be:
 
 ## State management
 
-Backups are based on [states](../reference/clan.core/state.md). A state defines
-which files should be backed up and how these files are obtained through
+Backups are based on [states](../reference/clan.core/state.md). A state
+defines which files should be backed up and how these files are obtained through
 pre/post backup and restore scripts.
 
 Here's an example for a user application `linkding`:
@@ -124,8 +123,7 @@ clan.core.state.linkding = {
 
 ## Managing backups
 
-In this section we go over how to manage your collection of backups with the
-clan command.
+In this section we go over how to manage your collection of backups with the clan command.
 
 ### Listing states
 
@@ -179,7 +177,7 @@ storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2
 
 ### Restoring backups
 
-For restoring a backup you have two options.
+For restoring a backup you have two options. 
 
 #### Full restoration
 
@@ -196,3 +194,6 @@ To restore only a specific service (e.g., `linkding`):
 ```bash
 clan backups restore --service linkding jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
 ```
+
+
+

docs/site/guides/clanServices.md

@@ -1,22 +1,16 @@
 # Using `clanServices`
 
-Clan's `clanServices` system is a composable way to define and deploy services
-across machines.
+Clan’s `clanServices` system is a composable way to define and deploy services across machines.
 
-This guide shows how to **instantiate** a `clanService`, explains how service
-definitions are structured in your inventory, and how to pick or create services
-from modules exposed by flakes.
+This guide shows how to **instantiate** a `clanService`, explains how service definitions are structured in your inventory, and how to pick or create services from modules exposed by flakes.
 
-The term **Multi-host-modules** was introduced previously in the
-[nixus repository](https://github.com/infinisil/nixus) and represents a similar
-concept.
+The term **Multi-host-modules** was introduced previously in the [nixus repository](https://github.com/infinisil/nixus) and represents a similar concept.
 
-______________________________________________________________________
+---
 
 ## Overview
 
-Services are used in `inventory.instances`, and then they attach to *roles* and
-*machines* — meaning you decide which machines run which part of the service.
+Services are used in `inventory.instances`, and then they attach to *roles* and *machines* — meaning you decide which machines run which part of the service.
 
 For example:
 
@@ -31,18 +25,15 @@ inventory.instances = {
 }
 ```
 
-This says: “Run borgbackup as a *client* on my *laptop* and *server1*, and as a
-*server* on *backup-box*.”
+This says: “Run borgbackup as a *client* on my *laptop* and *server1*, and as a *server* on *backup-box*.”
 
 ## Module source specification
 
-Each instance includes a reference to a **module specification** — this is how
-Clan knows which service module to use and where it came from. Usually one would
-just use `imports` but we needd to make the `module source` configurable via
-Python API. By default it is not required to specify the `module`, in which case
-it defaults to the preprovided services of clan-core.
+Each instance includes a reference to a **module specification** — this is how Clan knows which service module to use and where it came from.
+Usually one would just use `imports` but we needd to make the `module source` configurable via Python API.
+By default it is not required to specify the `module`, in which case it defaults to the preprovided services of clan-core.
 
-______________________________________________________________________
+---
 
 ## Override Example
 
@@ -74,8 +65,7 @@ inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"
 
 ## Simplified Example
 
-If only one instance is needed for a service and the service is a clan core
-service, the `module` definition can be omitted.
+If only one instance is needed for a service and the service is a clan core service, the `module` definition can be omitted.
 
 ```nix
 # Simplified way of specifying a single instance
@@ -94,8 +84,7 @@ inventory.instances = {
 
 Each role might expose configurable options
 
-See clan's [clanServices reference](../reference/clanServices/index.md) for
-available options
+See clan's [clanServices reference](../reference/clanServices/index.md) for available options
 
 ```nix
 inventory.instances = {
@@ -141,36 +130,30 @@ inventory.instances = {
 
 ## Picking a clanService
 
-You can use services exposed by Clan's core module library, `clan-core`.
+You can use services exposed by Clan’s core module library, `clan-core`.
 
-🔗 See:
-[List of Available Services in clan-core](../reference/clanServices/index.md)
+🔗 See: [List of Available Services in clan-core](../reference/clanServices/index.md)
 
 ## Defining Your Own Service
 
 You can also author your own `clanService` modules.
 
-🔗 Learn how to write your own service:
-[Authoring a service](../guides/services/community.md)
+🔗 Learn how to write your own service: [Authoring a service](../guides/services/community.md)
 
-You might expose your service module from your flake — this makes it easy for
-other people to also use your module in their clan.
+You might expose your service module from your flake — this makes it easy for other people to also use your module in their clan.
 
-______________________________________________________________________
+---
 
 ## 💡 Tips for Working with clanServices
 
-- You can add multiple inputs to your flake (`clan-core`, `your-org-modules`,
-  etc.) to mix and match services.
-- Each service instance is isolated by its key in `inventory.instances`,
-  allowing you to deploy multiple versions or roles of the same service type.
-- Roles can target different machines or be scoped dynamically.
+* You can add multiple inputs to your flake (`clan-core`, `your-org-modules`, etc.) to mix and match services.
+* Each service instance is isolated by its key in `inventory.instances`, allowing you to deploy multiple versions or roles of the same service type.
+* Roles can target different machines or be scoped dynamically.
 
-______________________________________________________________________
+---
 
-## What's Next?
-
-- [Author your own clanService →](../guides/services/community.md)
-- [Migrate from clanModules →](../guides/migrations/migrate-inventory-services.md)
+## What’s Next?
 
+* [Author your own clanService →](../guides/services/community.md)
+* [Migrate from clanModules →](../guides/migrations/migrate-inventory-services.md)
 <!-- TODO: * [Understand the architecture →](../explanation/clan-architecture.md) -->

docs/site/guides/contributing/debugging.md

@@ -1,21 +1,16 @@
+
 Here are some methods for debugging and testing the clan-cli
 
 ## Using a Development Branch
 
-To streamline your development process, I suggest not installing `clan-cli`.
-Instead, clone the `clan-core` repository and add `clan-core/pkgs/clan-cli/bin`
-to your PATH to use the checked-out version directly.
+To streamline your development process, I suggest not installing `clan-cli`. Instead, clone the `clan-core` repository and add `clan-core/pkgs/clan-cli/bin` to your PATH to use the checked-out version directly.
 
-!!! Note After cloning, navigate to `clan-core/pkgs/clan-cli` and execute
-`direnv allow` to activate the devshell. This will set up a symlink to nixpkgs
-at a specific location; without it, `clan-cli` won't function correctly.
+!!! Note
+    After cloning, navigate to `clan-core/pkgs/clan-cli` and execute `direnv allow` to activate the devshell. This will set up a symlink to nixpkgs at a specific location; without it, `clan-cli` won't function correctly.
 
-With this setup, you can easily use
-[breakpoint()](https://docs.python.org/3/library/pdb.html) to inspect the
-application's internal state as needed.
+With this setup, you can easily use [breakpoint()](https://docs.python.org/3/library/pdb.html) to inspect the application's internal state as needed.
 
-This approach is feasible because `clan-cli` only requires a Python interpreter
-and has no other dependencies.
+This approach is feasible because `clan-cli` only requires a Python interpreter and has no other dependencies.
 
 ```nix
 pkgs.mkShell {
@@ -31,17 +26,11 @@ pkgs.mkShell {
 
 ## Debugging nixos-anywhere
 
-If you encounter a bug in a complex shell script such as `nixos-anywhere`, start
-by replacing the `nixos-anywhere` command with a local checkout of the project,
-look in the [contribution](./CONTRIBUTING.md) section for an example.
+If you encounter a bug in a complex shell script such as `nixos-anywhere`, start by replacing the `nixos-anywhere` command with a local checkout of the project, look in the [contribution](./CONTRIBUTING.md) section for an example. 
 
 ## The Debug Flag
 
-You can enhance your debugging process with the `--debug` flag in the `clan`
-command. When you add this flag to any command, it displays all subprocess
-commands initiated by `clan` in a readable format, along with the source code
-position that triggered them. This feature makes it easier to understand and
-trace what's happening under the hood.
+You can enhance your debugging process with the `--debug` flag in the `clan` command. When you add this flag to any command, it displays all subprocess commands initiated by `clan` in a readable format, along with the source code position that triggered them. This feature makes it easier to understand and trace what's happening under the hood.
 
 ```bash
 $ clan machines list --debug                                                                          1 ↵
@@ -64,60 +53,49 @@ wintux
 
 ## VSCode
 
-If you're using VSCode, it has a handy feature that makes paths to source code
-files clickable in the integrated terminal. Combined with the previously
-mentioned techniques, this allows you to open a Clan in VSCode, execute a
-command like `clan machines list --debug`, and receive a printed path to the
-code that initiates the subprocess. With the `Ctrl` key (or `Cmd` on macOS) and
-a mouse click, you can jump directly to the corresponding line in the code file
-and add a `breakpoint()` function to it, to inspect the internal state.
+If you're using VSCode, it has a handy feature that makes paths to source code files clickable in the integrated terminal. Combined with the previously mentioned techniques, this allows you to open a Clan in VSCode, execute a command like `clan machines list --debug`, and receive a printed path to the code that initiates the subprocess. With the `Ctrl` key (or `Cmd` on macOS) and a mouse click, you can jump directly to the corresponding line in the code file and add a `breakpoint()` function to it, to inspect the internal state.
+
+
 
 ## Finding Print Messages
 
-To trace the origin of print messages in `clan-cli`, you can enable special
-debugging features using environment variables:
+To trace the origin of print messages in `clan-cli`, you can enable special debugging features using environment variables:
 
 - Set `TRACE_PRINT=1` to include the source location with each print message:
+    ```bash
+    export TRACE_PRINT=1
+    ```
+    When running commands with `--debug`, every print will show where it was triggered in the code.
 
-  ```bash
-  export TRACE_PRINT=1
-  ```
-
-  When running commands with `--debug`, every print will show where it was
-  triggered in the code.
-
-- To see a deeper stack trace for each print, set `TRACE_DEPTH` to the desired
-  number of stack frames (e.g., 3):
-
-  ```bash
-  export TRACE_DEPTH=3
-  ```
+- To see a deeper stack trace for each print, set `TRACE_DEPTH` to the desired number of stack frames (e.g., 3):
+    ```bash
+    export TRACE_DEPTH=3
+    ```
 
 ### Additional Debug Logging
 
-You can enable more detailed logging for specific components by setting these
-environment variables:
+You can enable more detailed logging for specific components by setting these environment variables:
 
 - `CLAN_DEBUG_NIX_SELECTORS=1` — verbose logs for flake.select operations
 - `CLAN_DEBUG_NIX_PREFETCH=1` — verbose logs for flake.prefetch operations
 - `CLAN_DEBUG_COMMANDS=1` — print the diffed environment of executed commands
 
 Example:
-
 ```bash
 export CLAN_DEBUG_NIX_SELECTORS=1
 export CLAN_DEBUG_NIX_PREFETCH=1
 export CLAN_DEBUG_COMMANDS=1
 ```
 
-These options help you pinpoint the source and context of print messages and
-debug logs during development.
+These options help you pinpoint the source and context of print messages and debug logs during development.
+
+
 
 ## Analyzing Performance
 
-To understand what's causing slow performance, set the environment variable
-`export CLAN_CLI_PERF=1`. When you complete a clan command, you'll see a summary
-of various performance metrics, helping you identify what's taking up time.
+To understand what's causing slow performance, set the environment variable `export CLAN_CLI_PERF=1`. When you complete a clan command, you'll see a summary of various performance metrics, helping you identify what's taking up time.
+
+
 
 ## See all possible packages and tests
 
@@ -127,8 +105,7 @@ To quickly show all possible packages and tests execute:
 nix flake show
 ```
 
-Under `checks` you will find all tests that are executed in our CI. Under
-`packages` you find all our projects.
+Under `checks` you will find all tests that are executed in our CI. Under `packages` you find all our projects.
 
 ```
 git+file:///home/lhebendanz/Projects/clan-core
@@ -163,54 +140,60 @@ git+file:///home/lhebendanz/Projects/clan-core
     └───default: template: Initialize a new clan flake
 ```
 
-You can execute every test separately by following the tree path
-`nix run .#checks.x86_64-linux.clan-pytest -L` for example.
+You can execute every test separately by following the tree path `nix run .#checks.x86_64-linux.clan-pytest -L` for example.
 
 ## Test Locally in Devshell with Breakpoints
 
-To test the CLI locally in a development environment and set breakpoints for
-debugging, follow these steps:
+To test the CLI locally in a development environment and set breakpoints for debugging, follow these steps:
 
-1. Run the following command to execute your tests and allow for debugging with
-   breakpoints:
+1. Run the following command to execute your tests and allow for debugging with breakpoints:
    ```bash
    cd ./pkgs/clan-cli
    pytest -n0 -s --maxfail=1 ./tests/test_nameofthetest.py
    ```
-   You can place `breakpoint()` in your Python code where you want to trigger a
-   breakpoint for debugging.
+   You can place `breakpoint()` in your Python code where you want to trigger a breakpoint for debugging.
 
 ## Test Locally in a Nix Sandbox
 
-To run tests in a Nix sandbox:
+To run tests in a Nix sandbox, you have two options depending on whether your test functions have been marked as impure or not:
+
+### Running Tests Marked as Impure
+
+If your test functions need to execute `nix build` and have been marked as impure because you can't execute `nix build` inside a Nix sandbox, use the following command:
 
 ```bash
-nix build .#checks.x86_64-linux.clan-pytest-with-core
+nix run .#impure-checks -L
 ```
 
+This command will run the impure test functions.
+
+### Running Pure Tests
+
+For test functions that have not been marked as impure and don't require executing `nix build`, you can use the following command:
+
 ```bash
-nix build .#checks.x86_64-linux.clan-pytest-without-core
+nix build .#checks.x86_64-linux.clan-pytest --rebuild
 ```
 
+This command will run all pure test functions.
+
 ### Inspecting the Nix Sandbox
 
 If you need to inspect the Nix sandbox while running tests, follow these steps:
 
-1. Insert an endless sleep into your test code where you want to pause the
-   execution. For example:
+1. Insert an endless sleep into your test code where you want to pause the execution. For example:
 
    ```python
    import time
    time.sleep(3600)  # Sleep for one hour
    ```
 
-2. Use `cntr` and `psgrep` to attach to the Nix sandbox. This allows you to
-   interactively debug your code while it's paused. For example:
+2. Use `cntr` and `psgrep` to attach to the Nix sandbox. This allows you to interactively debug your code while it's paused. For example:
 
    ```bash
    psgrep <your_python_process_name>
    cntr attach <container id, container name or process id>
    ```
 
-Or you can also use the
-[nix breakpoint hook](https://nixos.org/manual/nixpkgs/stable/#breakpointhook)
+Or you can also use the [nix breakpoint hook](https://nixos.org/manual/nixpkgs/stable/#breakpointhook)
+

docs/site/guides/contributing/testing.md

@@ -2,11 +2,9 @@
 
 Each feature added to clan should be tested extensively via automated tests.
 
-This document covers different methods of automated testing, including creating,
-running and debugging such tests.
+This document covers different methods of automated testing, including creating, running and debugging such tests.
 
-In order to test the behavior of clan, different testing frameworks are used
-depending on the concern:
+In order to test the behavior of clan, different testing frameworks are used depending on the concern:
 
 - NixOS VM tests: for high level integration
 - NixOS container tests: for high level integration
@@ -15,48 +13,37 @@ depending on the concern:
 
 ## NixOS VM Tests
 
-The
-[NixOS VM Testing Framework](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests)
-is used to create high level integration tests, by running one or more VMs
-generated from a specified config. Commands can be executed on the booted
-machine(s) to verify a deployment of a service works as expected. All machines
-within a test are connected by a virtual network. Internet access is not
-available.
+The [NixOS VM Testing Framework](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests) is used to create high level integration tests, by running one or more VMs generated from a specified config. Commands can be executed on the booted machine(s) to verify a deployment of a service works as expected. All machines within a test are connected by a virtual network. Internet access is not available.
 
 ### When to use VM tests
 
-- testing that a service defined through a clan module works as expected after
-  deployment
+- testing that a service defined through a clan module works as expected after deployment
 - testing clan-cli subcommands which require accessing a remote machine
 
 ### When not to use VM tests
 
-NixOS VM Tests are slow and expensive. They should only be used for testing high
-level integration of components. VM tests should be avoided wherever it is
-possible to implement a cheaper unit test instead.
+NixOS VM Tests are slow and expensive. They should only be used for testing high level integration of components.
+VM tests should be avoided wherever it is possible to implement a cheaper unit test instead.
 
-- testing detailed behavior of a certain clan-cli command -> use unit testing
-  via pytest instead
+- testing detailed behavior of a certain clan-cli command -> use unit testing via pytest instead
 - regression testing -> add a unit test
 
 ### Finding examples for VM tests
 
 Existing nixos vm tests in clan-core can be found by using ripgrep:
-
 ```shellSession
 rg self.clanLib.test.baseTest
 ```
 
 ### Locating definitions of failing VM tests
 
-All nixos vm tests in clan are exported as individual flake outputs under
-`checks.x86_64-linux.{test-attr-name}`. If a test fails in CI:
+All nixos vm tests in clan are exported as individual flake outputs under `checks.x86_64-linux.{test-attr-name}`.
+If a test fails in CI:
 
-- look for the job name of the test near the top if the CI Job page, like, for
-  example `gitea:clan/clan-core#checks.x86_64-linux.borgbackup/1242`
-- in this case `checks.x86_64-linux.borgbackup` is the attribute path
-- note the last element of that attribute path, in this case `borgbackup`
-- search for the attribute name inside the `/checks` directory via ripgrep
+  - look for the job name of the test near the top if the CI Job page, like, for example `gitea:clan/clan-core#checks.x86_64-linux.borgbackup/1242`
+  - in this case `checks.x86_64-linux.borgbackup` is the attribute path
+  - note the last element of that attribute path, in this case `borgbackup`
+  - search for the attribute name inside the `/checks` directory via ripgrep
 
 example: locating the vm test named `borgbackup`:
 
@@ -70,15 +57,14 @@ $ rg "borgbackup =" ./checks
 
 ### Adding vm tests
 
-Create a nixos test module under `/checks/{name}/default.nix` and import it in
-`/checks/flake-module.nix`.
+Create a nixos test module under `/checks/{name}/default.nix` and import it in `/checks/flake-module.nix`.
+
 
 ### Running VM tests
 
 ```shellSession
 nix build .#checks.x86_64-linux.{test-attr-name}
 ```
-
 (replace `{test-attr-name}` with the name of the test)
 
 ### Debugging VM tests
@@ -87,14 +73,12 @@ The following techniques can be used to debug a VM test:
 
 #### Print Statements
 
-Locate the definition (see above) and add print statements, like, for example
-`print(client.succeed("systemctl --failed"))`, then re-run the test via
-`nix build` (see above)
+Locate the definition (see above) and add print statements, like, for example `print(client.succeed("systemctl --failed"))`, then re-run the test via `nix build` (see above)
 
 #### Interactive Shell
 
 - Execute the vm test outside the nix Sandbox via the following command:
-  `nix run .#checks.x86_64-linux.{test-attr-name}.driver -- --interactive`
+`nix run .#checks.x86_64-linux.{test-attr-name}.driver -- --interactive`
 - Then run the commands in the machines manually, like for example:
   ```python3
     start_all()
@@ -103,22 +87,19 @@ Locate the definition (see above) and add print statements, like, for example
 
 #### Breakpoints
 
-To get an interactive shell at a specific line in the VM test script, add a
-`breakpoint()` call before the line to debug, then run the test outside of the
-sandbox via: `nix run .#checks.x86_64-linux.{test-attr-name}.driver`
+To get an interactive shell at a specific line in the VM test script, add a `breakpoint()` call before the line to debug, then run the test outside of the sandbox via:
+`nix run .#checks.x86_64-linux.{test-attr-name}.driver`
+
 
 ## NixOS Container Tests
 
-Those are very similar to NixOS VM tests, as in they run virtualized nixos
-machines, but instead of using VMs, they use containers which are much cheaper
-to launch. As of now the container test driver is a downstream development in
-clan-core. Basically everything stated under the NixOS VM tests sections applies
-here, except some limitations.
+Those are very similar to NixOS VM tests, as in they run virtualized nixos machines, but instead of using VMs, they use containers which are much cheaper to launch.
+As of now the container test driver is a downstream development in clan-core.
+Basically everything stated under the NixOS VM tests sections applies here, except some limitations.
 
 Limitations:
 
-- Cannot run in interactive mode, however while the container test runs, it logs
-  a nsenter command that can be used to log into each of the container.
+- Cannot run in interactive mode, however while the container test runs, it logs a nsenter command that can be used to log into each of the container.
 - setuid binaries don't work
 
 ### Where to find examples for NixOS container tests
@@ -129,10 +110,10 @@ Existing NixOS container tests in clan-core can be found by using `ripgrep`:
 rg self.clanLib.test.containerTest
 ```
 
+
 ## Python tests via pytest
 
-Since the Clan CLI is written in python, the `pytest` framework is used to
-define unit tests and integration tests via python
+Since the Clan CLI is written in python, the `pytest` framework is used to define unit tests and integration tests via python
 
 Due to superior efficiency,
 
@@ -140,52 +121,43 @@ Due to superior efficiency,
 
 - writing unit tests for python functions and modules, or bugfixes of such
 - all integrations tests that do not require building or running a nixos machine
-- impure integrations tests that require internet access (very rare, try to
-  avoid)
+- impure integrations tests that require internet access (very rare, try to avoid)
+
 
 ### When not to use python tests
 
-- integrations tests that require building or running a nixos machine (use NixOS
-  VM or container tests instead)
+- integrations tests that require building or running a nixos machine (use NixOS VM or container tests instead)
 - testing behavior of a nix function or library (use nix eval tests instead)
 
 ### Finding examples of python tests
 
 Existing python tests in clan-core can be found by using `ripgrep`:
-
 ```shellSession
 rg "import pytest"
 ```
 
 ### Locating definitions of failing python tests
 
-If any python test fails in the CI pipeline, an error message like this can be
-found at the end of the log:
-
+If any python test fails in the CI pipeline, an error message like this can be found at the end of the log:
 ```
 ...
 FAILED tests/test_machines_cli.py::test_machine_delete - clan_lib.errors.ClanError: Template 'new-machine' not in 'inputs.clan-core
 ...
 ```
 
-In this case the test is defined in the file `/tests/test_machines_cli.py` via
-the test function `test_machine_delete`.
+In this case the test is defined in the file `/tests/test_machines_cli.py` via the test function `test_machine_delete`.
 
 ### Adding python tests
 
-If a specific python module is tested, the test should be located near the
-tested module in a subdirectory called `./tests` If the test is not clearly
-related to a specific module, put it in the top-level `./tests` directory of the
-tested python package. For `clan-cli` this would be
-`/pkgs/clan-cli/clan_cli/tests`. All filenames must be prefixed with `test_` and
-test functions prefixed with `test_` for pytest to discover them.
+If a specific python module is tested, the test should be located near the tested module in a subdirectory called `./tests`
+If the test is not clearly related to a specific module, put it in the top-level `./tests` directory of the tested python package. For `clan-cli` this would be `/pkgs/clan-cli/clan_cli/tests`.
+All filenames must be prefixed with `test_` and test functions prefixed with `test_` for pytest to discover them.
 
 ### Running python tests
 
 #### Running all python tests
 
-To run all python tests which are executed in the CI pipeline locally, use this
-`nix build` command
+To run all python tests which are executed in the CI pipeline locally, use this `nix build` command
 
 ```shellSession
 nix build .#checks.x86_64-linux.clan-pytest-{with,without}-core
@@ -196,27 +168,21 @@ nix build .#checks.x86_64-linux.clan-pytest-{with,without}-core
 To run a specific python test outside the nix sandbox
 
 1. Enter the development environment of the python package, by either:
-
-- Having direnv enabled and entering the directory of the package (eg.
-  `/pkgs/clan-cli`)
-- Or using the command `select-shell {package}` in the top-level dev shell of
-  clan-core, (eg. `switch-shell clan-cli`)
-
+  - Having direnv enabled and entering the directory of the package (eg. `/pkgs/clan-cli`)
+  - Or using the command `select-shell {package}` in the top-level dev shell of clan-core, (eg. `switch-shell clan-cli`)
 2. Execute the test via pytest using issuing
-   `pytest ./path/to/test_file.py:test_function_name -s -n0`
+  `pytest ./path/to/test_file.py:test_function_name -s -n0`
+
+The flags `-sn0` are useful to forwards all stdout/stderr output to the terminal and be able to debug interactively via `breakpoint()`.
 
-The flags `-sn0` are useful to forwards all stdout/stderr output to the terminal
-and be able to debug interactively via `breakpoint()`.
 
 ### Debugging python tests
 
-To debug a specific python test, find its definition (see above) and make sure
-to enter the correct dev environment for that python package.
+To debug a specific python test, find its definition (see above) and make sure to enter the correct dev environment for that python package.
 
 Modify the test and add `breakpoint()` statements to it.
 
-Execute the test using the flags `-sn0` in order to get an interactive shell at
-the breakpoint:
+Execute the test using the flags `-sn0` in order to get an interactive shell at the breakpoint:
 
 ```shelSession
 pytest ./path/to/test_file.py:test_function_name -sn0
@@ -268,9 +234,7 @@ Failing nix eval tests look like this:
     > error: Tests failed
 ```
 
-To locate the definition, find the flake attribute name of the failing test near
-the top of the CI Job page, like for example
-`gitea:clan/clan-core#checks.x86_64-linux.eval-lib-values/1242`.
+To locate the definition, find the flake attribute name of the failing test near the top of the CI Job page, like for example `gitea:clan/clan-core#checks.x86_64-linux.eval-lib-values/1242`.
 
 In this case `eval-lib-values` is the attribute we are looking for.
 
@@ -283,8 +247,7 @@ lib/values/flake-module.nix
 grmpf@grmpf-nix ~/p/c/clan-core (test-docs)>
 ```
 
-In this case the test is defined in the file `lib/values/flake-module.nix` line
-21
+In this case the test is defined in the file `lib/values/flake-module.nix` line 21
 
 ### Adding nix eval tests
 
@@ -292,22 +255,20 @@ In clan core, the following pattern is usually followed:
 
 - tests are put in a `test.nix` file
 - a CI Job is exposed via a `flake-module.nix`
-- that `flake-module.nix` is imported via the `flake.nix` at the root of the
-  project
+- that `flake-module.nix` is imported via the `flake.nix` at the root of the project
 
 For example see `/lib/values/{test.nix,flake-module.nix}`.
 
 ### Running nix eval tests
 
-Since all nix eval tests are exposed via the flake outputs, they can be ran via
-`nix build`:
+Since all nix eval tests are exposed via the flake outputs, they can be ran via `nix build`:
 
 ```shellSession
 nix build .#checks.x86_64-linux.{test-attr-name}
 ```
 
-For quicker iteration times, instead of `nix build` use the `nix-unit` command
-available in the dev environment. Example:
+For quicker iteration times, instead of `nix build` use the `nix-unit` command available in the dev environment.
+Example:
 
 ```shellSession
 nix-unit --flake .#legacyPackages.x86_64-linux.{test-attr-name}
@@ -315,23 +276,19 @@ nix-unit --flake .#legacyPackages.x86_64-linux.{test-attr-name}
 
 ### Debugging nix eval tests
 
-Follow the instructions above to find the definition of the test, then use one
-of the following techniques:
+Follow the instructions above to find the definition of the test, then use one of the following techniques:
 
 #### Print debugging
 
-Add `lib.trace` or `lib.traceVal` statements in order to print some variables
-during evaluation
+Add `lib.trace` or `lib.traceVal` statements in order to print some variables during evaluation
 
 #### Nix repl
 
 Use `nix repl` to evaluate and inspect the test.
 
-Each test consists of an `expr` (expression) and an `expected` field. `nix-unit`
-simply checks if `expr == expected` and prints the diff if that's not the case.
+Each test consists of an `expr` (expression) and an `expected` field. `nix-unit` simply checks if `expr == expected` and prints the diff if that's not the case.
 
-`nix repl` can be used to inspect an `expr` manually, or any other variables
-that you choose to expose.
+`nix repl` can be used to inspect an `expr` manually, or any other variables that you choose to expose.
 
 Example:
 

docs/site/guides/disk-encryption.md

@@ -1,26 +1,34 @@
-This guide provides an example setup for a single-disk ZFS system with native
-encryption, accessible for decryption remotely.
 
-!!! Warning This configuration only applies to `systemd-boot` enabled systems
-and **requires** UEFI booting.
+This guide provides an example setup for a single-disk ZFS system with native encryption, accessible for decryption remotely.
 
-Replace the highlighted lines with your own disk-id. You can find our your
-disk-id by executing:
+!!! Warning
+    This configuration only applies to `systemd-boot` enabled systems and **requires** UEFI booting.
 
+
+Replace the highlighted lines with your own disk-id.
+You can find our your disk-id by executing:
 ```bash
 lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
 ```
 
-=== "**Single Disk**" Below is the configuration for `disko.nix`
-`nix hl_lines="13 53"       --8<-- "docs/code-examples/disko-single-disk.nix"     `
 
-=== "**Raid 1**" Below is the configuration for `disko.nix`
-`nix hl_lines="13 53 54"       --8<-- "docs/code-examples/disko-raid.nix"     `
+=== "**Single Disk**"
+    Below is the configuration for `disko.nix`
+    ```nix hl_lines="13 53"
+      --8<-- "docs/code-examples/disko-single-disk.nix"
+    ```
 
-Below is the configuration for `initrd.nix`. Replace `<yourkey>` with your ssh
-public key. Replace `kernelModules` with the ethernet module loaded one on your
-target machine.
 
+
+=== "**Raid 1**"
+    Below is the configuration for `disko.nix`
+    ```nix hl_lines="13 53 54"
+      --8<-- "docs/code-examples/disko-raid.nix"
+    ```
+
+Below is the configuration for `initrd.nix`.
+Replace `<yourkey>` with your ssh public key.
+Replace `kernelModules` with the ethernet module loaded one on your target machine.
 ```nix hl_lines="18 29"
 {config, pkgs, ...}:
 
@@ -57,8 +65,7 @@ target machine.
 
 ## Copying SSH Public Key
 
-Before starting the installation process, ensure that the SSH public key is
-copied to the NixOS installer.
+Before starting the installation process, ensure that the SSH public key is copied to the NixOS installer.
 
 1. Copy your public SSH key to the installer, if it has not been copied already:
 
@@ -86,8 +93,7 @@ nano /tmp/secret.key
 blkdiscard /dev/disk/by-id/<installdisk>
 ```
 
-4. Run `clan` machines install, only running kexec and disko, with the following
-   command:
+4. Run `clan` machines install, only running kexec and disko, with the following command:
 
 ```bash
 clan machines install gchq-local --target-host root@nixos-installer --phases kexec,disko
@@ -113,29 +119,25 @@ zfs set keylocation=prompt zroot/root
 CTRL+D
 ```
 
-4. Locally generate ssh host keys. You only need to generate ones for the
-   algorithms you're using in `authorizedKeys`.
+4. Locally generate ssh host keys. You only need to generate ones for the algorithms you're using in `authorizedKeys`.
 
 ```bash
 ssh-keygen -q -N "" -C "" -t ed25519 -f ./initrd_host_ed25519_key
 ssh-keygen -q -N "" -C "" -t rsa -b 4096 -f ./initrd_host_rsa_key
 ```
 
-5. Securely copy your local initrd ssh host keys to the installer's `/mnt`
-   directory:
+5. Securely copy your local initrd ssh host keys to the installer's `/mnt` directory:
 
 ```bash
 scp ./initrd_host* root@nixos-installer.local:/mnt/var/lib/
 ```
 
 6. Install nixos to the mounted partitions
-
 ```bash
 clan machines install gchq-local --target-host root@nixos-installer --phases install
 ```
 
-7. After the installation process, unmount `/mnt/boot`, change the ZFS
-   mountpoints and unmount all the ZFS volumes by exporting the zpool:
+7. After the installation process, unmount `/mnt/boot`, change the ZFS mountpoints and unmount all the ZFS volumes by exporting the zpool:
 
 ```bash
 umount /mnt/boot
@@ -162,9 +164,6 @@ ssh -p 7172 root@192.168.178.141
 systemd-tty-ask-password-agent
 ```
 
-After completing these steps, your NixOS should be successfully installed and
-ready for use.
+After completing these steps, your NixOS should be successfully installed and ready for use.
 
-**Note:** Replace `root@nixos-installer.local` and `192.168.178.141` with the
-appropriate user and IP addresses for your setup. Also, adjust `<SYS_PATH>` to
-reflect the correct system path for your environment.
+**Note:** Replace `root@nixos-installer.local` and `192.168.178.141` with the appropriate user and IP addresses for your setup. Also, adjust `<SYS_PATH>` to reflect the correct system path for your environment.

docs/site/guides/disko-templates/community.md

@@ -1,9 +1,9 @@
-!!! Danger ":fontawesome-solid-road-barrier: Under Construction
-:fontawesome-solid-road-barrier:" Currently under construction use with caution
 
-```
-:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
-```
+!!! Danger ":fontawesome-solid-road-barrier: Under Construction :fontawesome-solid-road-barrier:"
+    Currently under construction use with caution
+
+    :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
+
 
 ## Structure
 
@@ -20,16 +20,13 @@ A disk template consists of exactly two files
 
 ## `default.nix`
 
-Placeholders are filled with their machine specific options when a template is
-used for a machine.
+Placeholders are filled with their machine specific options when a template is used for a machine.
 
 The user can choose any valid options from the hardware report.
 
-The file itself is then copied to `machines/{machineName}/disko.nix` and will be
-automatically loaded by the machine.
+The file itself is then copied to `machines/{machineName}/disko.nix` and will be automatically loaded by the machine.
 
 `single-disk/default.nix`
-
 ```
 {
   disko.devices = {
@@ -45,11 +42,9 @@ automatically loaded by the machine.
 
 ## Placeholders
 
-Each template must declare the options of its placeholders depending on the
-hardware-report.
+Each template must declare the options of its placeholders depending on the hardware-report.
 
 `api/disk.py`
-
 ```py
 templates: dict[str, dict[str, Callable[[dict[str, Any]], Placeholder]]] = {
     "single-disk": {
@@ -61,25 +56,24 @@ templates: dict[str, dict[str, Callable[[dict[str, Any]], Placeholder]]] = {
 }
 ```
 
-Introducing new local or global placeholders requires contributing to clan-core
-`api/disks.py`.
+Introducing new local or global placeholders requires contributing to clan-core `api/disks.py`.
 
 ### Predefined placeholders
 
 Some placeholders provide predefined functionality
 
-- `uuid`: In most cases we recommend adding a unique id to all disks. This
-  prevents the system to false boot from i.e. hot-plugged devices.
-  ```
-  disko.devices = {
-    disk = {
-      main = {
-        name = "main-{{uuid}}";
-        ...
+- `uuid`: In most cases we recommend adding a unique id to all disks. This prevents the system to false boot from i.e. hot-plugged devices.
+    ```
+    disko.devices = {
+      disk = {
+        main = {
+          name = "main-{{uuid}}";
+          ...
+        }
       }
     }
-  }
-  ```
+    ```
+
 
 ## Readme
 
@@ -96,5 +90,5 @@ Use this schema for simple setups where ....
 
 ```
 
-The format and fields of this file is not clear yet. We might change that once
-fully implemented.
+
+The format and fields of this file is not clear yet. We might change that once fully implemented.

docs/site/guides/flake-parts.md

@@ -1,13 +1,11 @@
-Clan supports integration with [flake-parts](https://flake.parts/), a framework
-for constructing your `flake.nix` using modules.
+
+Clan supports integration with [flake-parts](https://flake.parts/), a framework for constructing your `flake.nix` using modules.
 
 To construct your Clan using flake-parts, follow these steps:
 
 ## Update Your Flake Inputs
 
-To begin, you'll need to add `flake-parts` as a new dependency in your flake's
-inputs. This is alongside the already existing dependencies, such as `clan-core`
-and `nixpkgs`. Here's how you can update your `flake.nix` file:
+To begin, you'll need to add `flake-parts` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `clan-core` and `nixpkgs`. Here's how you can update your `flake.nix` file:
 
 ```nix
 # flake.nix
@@ -29,9 +27,7 @@ inputs = {
 
 ## Import the Clan flake-parts Module
 
-After updating your flake inputs, the next step is to import the Clan
-flake-parts module. This will make the [Clan options](/options) available within
-`mkFlake`.
+After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../options.md) available within `mkFlake`.
 
 ```nix
 {
@@ -49,8 +45,7 @@ flake-parts module. This will make the [Clan options](/options) available within
 
 ## Configure Clan Settings and Define Machines
 
-Next you'll need to configure Clan wide settings and define machines, here's an
-example of how `flake.nix` should look:
+Next you'll need to configure Clan wide settings and define machines, here's an example of how `flake.nix` should look:
 
 ```nix
 {
@@ -95,9 +90,7 @@ example of how `flake.nix` should look:
 }
 ```
 
-For detailed information about configuring `flake-parts` and the available
-options within Clan, refer to the
-[Clan module](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix)
-documentation.
+For detailed information about configuring `flake-parts` and the available options within Clan,
+refer to the [Clan module](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) documentation.
 
-______________________________________________________________________
+---

docs/site/guides/getting-started/add-machines.md

@@ -2,11 +2,9 @@
 
 Machines can be added using the following methods
 
-- Create a file `machines/{machine_name}/configuration.nix` (See:
-  [File Autoincludes](../../concepts/autoincludes.md))
-- Imperative via cli command: `clan machines create`
-- Editing nix expressions in flake.nix See
-  \[`clan-core.lib.clan`\](/options/?scope=Flake Options (clan.nix file))
+- Editing nix expressions in flake.nix (i.e. via `clan-core.lib.clan`)
+- Editing machines/`machine_name`/configuration.nix (automatically included if it exists)
+- `clan machines create` (imperative)
 
 See the complete [list](../../concepts/autoincludes.md) of auto-loaded files.
 
@@ -14,49 +12,44 @@ See the complete [list](../../concepts/autoincludes.md) of auto-loaded files.
 
 === "clan.nix (declarative)"
 
-````
-```{.nix hl_lines="3-4"}
-{
-    inventory.machines = {
-        # Define a machine
-        jon = { };
-    };
+    ```{.nix hl_lines="3-4"}
+    {
+        inventory.machines = {
+            # Define a machine
+            jon = { };
+        };
 
-    # Additional NixOS configuration can be added here.
-    # machines/jon/configuration.nix will be automatically imported.
-    # See: https://docs.clan.lol/guides/more-machines/#automatic-registration
-    machines = {
-        # jon = { config, ... }: {
-        #   environment.systemPackages = [ pkgs.asciinema ];
-        # };
-    };
-}
-```
-````
+        # Additional NixOS configuration can be added here.
+        # machines/jon/configuration.nix will be automatically imported.
+        # See: https://docs.clan.lol/guides/more-machines/#automatic-registration
+        machines = {
+            # jon = { config, ... }: {
+            #   environment.systemPackages = [ pkgs.asciinema ];
+            # };
+        };
+    }
+    ```
 
 === "CLI (imperative)"
 
-````
-```sh
-clan machines create jon
-```
+    ```sh
+    clan machines create jon
+    ```
+
+    The imperative command might create a machine folder in `machines/jon`
+    And might persist information in `inventory.json`
 
-The imperative command might create a machine folder in `machines/jon`
-And might persist information in `inventory.json`
-````
 
 ### Configuring a machine
 
-!!! Note The option: `inventory.machines.<name>` is used to define metadata
-about the machine That includes for example `deploy.targethost` `machineClass`
-or `tags`
+!!! Note
+    The option: `inventory.machines.<name>` is used to define metadata about the machine
+    That includes for example `deploy.targethost` `machineClass` or `tags`
 
-```
-The option: `machines.<name>` is used to add extra *nixosConfiguration* to a machine
-```
+    The option: `machines.<name>` is used to add extra *nixosConfiguration* to a machine
 
-Add the following to your `clan.nix` file for each machine. This example
-demonstrates what is needed based on a machine called `jon`:
+Add the following to your `clan.nix` file for each machine.
+This example demonstrates what is needed based on a machine called `jon`:
 
 ```{.nix .annotate title="clan.nix" hl_lines="3-6 15-19"}
 {
@@ -82,10 +75,8 @@ demonstrates what is needed based on a machine called `jon`:
 }
 ```
 
-1. Tags can be used to automatically add this machine to services later on. -
-   You dont need to set this now.
-2. Add your *ssh key* here - That will ensure you can always login to your
-   machine via *ssh* in case something goes wrong.
+1. Tags can be used to automatically add this machine to services later on. - You dont need to set this now.
+2. Add your *ssh key* here - That will ensure you can always login to your machine via *ssh* in case something goes wrong.
 
 ### (Optional) Create a `configuration.nix`
 
@@ -104,9 +95,8 @@ demonstrates what is needed based on a machine called `jon`:
 
 ### (Optional) Renaming a Machine
 
-Older templates included static machine folders like `jon` and `sara`. If your
-setup still uses such static machines, you can rename a machine folder to match
-your own machine name:
+Older templates included static machine folders like `jon` and `sara`.
+If your setup still uses such static machines, you can rename a machine folder to match your own machine name:
 
 ```bash
 git mv ./machines/jon ./machines/<your-machine-name>
@@ -114,8 +104,8 @@ git mv ./machines/jon ./machines/<your-machine-name>
 
 Since your Clan configuration lives inside a Git repository, remember:
 
-- Only files tracked by Git (`git add`) are recognized.
-- Whenever you add, rename, or remove files, run:
+* Only files tracked by Git (`git add`) are recognized.
+* Whenever you add, rename, or remove files, run:
 
 ```bash
 git add ./machines/<your-machine-name>
@@ -123,17 +113,14 @@ git add ./machines/<your-machine-name>
 
 to stage the changes.
 
-______________________________________________________________________
+---
 
 ### (Optional) Removing a Machine
 
-If you want to work with a single machine for now, you can remove other machine
-entries both from your `flake.nix` and from the `machines` directory. For
-example, to remove the machine `sara`:
+If you want to work with a single machine for now, you can remove other machine entries both from your `flake.nix` and from the `machines` directory. For example, to remove the machine `sara`:
 
 ```bash
 git rm -rf ./machines/sara
 ```
 
-Make sure to also remove or update any references to that machine in your
-`nix files` or `inventory.json` if you have any of that
+Make sure to also remove or update any references to that machine in your `nix files` or `inventory.json` if you have any of that

docs/site/guides/getting-started/add-services.md

@@ -1,23 +1,19 @@
 # How to add services
 
-A service in clan is a self-contained, reusable unit of system configuration
-that provides a specific piece of functionality across one or more machines.
+A service in clan is a self-contained, reusable unit of system configuration that provides a specific piece of functionality across one or more machines.
 
-Think of it as a recipe for running a tool — like automatic backups, VPN
-networking, monitoring, etc.
+Think of it as a recipe for running a tool — like automatic backups, VPN networking, monitoring, etc.
 
 In Clan Services are multi-Host & role-based:
 
-- Roles map machines to logical service responsibilities, enabling structured,
-  clean deployments.
+- Roles map machines to logical service responsibilities, enabling structured, clean deployments.
 
 - You can use tags instead of explicit machine names.
 
 To learn more: [Guide about clanService](../clanServices.md)
 
-!!! Important It is recommended to add at least one networking service such as
-`zerotier` that allows to reach all your clan machines from your setup computer
-across the globe.
+!!! Important
+    It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe.
 
 ## Configure a Zerotier Network (recommended)
 
@@ -44,10 +40,8 @@ across the globe.
 }
 ```
 
-1. See [reference/clanServices](../../reference/clanServices/index.md) for all
-   available services and how to configure them. Or read
-   [authoring/clanServices](../../guides/services/community.md) if you want to
-   bring your own
+1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them.
+   Or read [authoring/clanServices](../../guides/services/community.md) if you want to bring your own
 
 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine.
 
@@ -78,9 +72,6 @@ Adding the following services is recommended for most users:
 }
 ```
 
-1. The `admin` service will generate a **root-password** and **add your
-   ssh-key** that allows for convienient administration.
-2. Equivalent to directly setting `authorizedKeys` like in
-   [configuring a machine](./add-machines.md#configuring-a-machine)
-3. Adds `user = jon` as a user on all machines. Will create a `home` directory,
-   and prompt for a password before deployment.
+1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration.
+2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](./add-machines.md#configuring-a-machine)
+3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.

docs/site/guides/getting-started/add-user.md

@@ -2,9 +2,8 @@
 
 !!! Note "Under construction"
 
-The users concept of clan is not done yet. This guide outlines some solutions
-from our community. Defining users can be done in many different ways. We want
-to highlight two approaches:
+The users concept of clan is not done yet. This guide outlines some solutions from our community.
+Defining users can be done in many different ways. We want to highlight two approaches:
 
 - Using clan's [users](../../reference/clanServices/users.md) service.
 - Using a custom approach.
@@ -13,10 +12,8 @@ to highlight two approaches:
 
 To add a first *user* this guide will be leveraging two things:
 
-- [clanServices](../../reference/clanServices/index.md): Allows to bind
-  arbitrary logic to something we call an `ìnstance`.
-- [clanServices/users](../../reference/clanServices/users.md): Implements logic
-  for adding a single user perInstance.
+- [clanServices](../../reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`.
+- [clanServices/users](../../reference/clanServices/users.md): Implements logic for adding a single user perInstance.
 
 The example shows how to add a user called `jon`:
 
@@ -48,23 +45,19 @@ The example shows how to add a user called `jon`:
 }
 ```
 
-1. Add `user = jon` as a user on all machines. Will create a `home` directory,
-   and prompt for a password before deployment.
+1. Add `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.
 2. Add this user to `all` machines
 3. Define the `name` of the user to be `jon`
 
-The `users` service creates a `/home/jon` directory, allows `jon` to sign in and
-will take care of the user's password.
+The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the user's password.
 
-For more information see
-[clanService/users](../../reference/clanServices/users.md)
+For more information see [clanService/users](../../reference/clanServices/users.md)
 
 ## Using a custom approach
 
-Some people like to define a `users` folder in their repository root. That
-allows to bind all user specific logic to a single place (`default.nix`) Which
-can be imported into individual machines to make the user available on that
-machine.
+Some people like to define a `users` folder in their repository root.
+That allows to bind all user specific logic to a single place (`default.nix`)
+Which can be imported into individual machines to make the user available on that machine.
 
 ```bash
 .
@@ -79,11 +72,10 @@ machine.
 
 ## using [home-manager](https://github.com/nix-community/home-manager)
 
-When using clan's `users` service it is possible to define extraModules. In fact
-this is always possible when using clan's services.
+When using clan's `users` service it is possible to define extraModules.
+In fact this is always possible when using clan's services.
 
-We can use this property of clan services to bind a nixosModule to the user,
-which configures home-manager.
+We can use this property of clan services to bind a nixosModule to the user, which configures home-manager.
 
 ```{.nix title="clan.nix" hl_lines="22"}
 {
@@ -115,12 +107,11 @@ which configures home-manager.
 }
 ```
 
-1. Type `path` or `string`: Must point to a separate file. Inlining a module is
-   not possible
+1. Type `path` or `string`: Must point to a separate file. Inlining a module is not possible
 
-!!! Note "This is inspiration" Our community might come up with better solutions
-soon. We are seeking contributions to improve this pattern if you have a nicer
-solution in mind.
+!!! Note "This is inspiration"
+    Our community might come up with better solutions soon.
+    We are seeking contributions to improve this pattern if you have a nicer solution in mind.
 
 ```nix title="users/jon/home.nix"
 # NixOS module to import home-manager and the home-manager configuration of 'jon'

docs/site/guides/getting-started/choose-disk.md

@@ -1,10 +1,8 @@
 # Configure Disk Config
 
-By default clan uses [disko](https://github.com/nix-community/disko) which
-allows for declarative disk partitioning.
+By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning.
 
 To see what disk templates are available run:
-
 ```{.shellSession hl_lines="10" .no-copy}
 $ clan templates list
 
@@ -24,14 +22,13 @@ Available 'machine' templates
 │   └── test-morph-template: Morph a machine
 ```
 
-For this guide we will select the `single-disk` template, that uses
-`A simple ext4 disk with a single partition`.
 
-!!! tip For advanced partitioning, see
-[Disko templates](https://github.com/nix-community/disko-templates) or
-[Disko examples](https://github.com/nix-community/disko/tree/master/example).
-You can also
-[contribute a disk template to clan core](https://docs.clan.lol/guides/disko-templates/community/)
+For this guide we will select the `single-disk` template, that uses `A simple ext4 disk with a single partition`.
+
+!!! tip
+    For advanced partitioning, see [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example).
+    You can also [contribute a disk template to clan core](https://docs.clan.lol/guides/disko-templates/community/)
+
 
 To setup a disk schema for a machine run
 
@@ -58,20 +55,22 @@ Should now be successful
 Applied disk template 'single-disk' to machine 'jon'
 ```
 
-A disko.nix file should be created in `machines/jon` You can have a look and
-customize it if needed.
+A disko.nix file should be created in `machines/jon`
+You can have a look and customize it if needed.
 
-!!! Danger Don't change the `disko.nix` after the machine is installed for the
-first time, unless you really know what you are doing. Changing disko
-configuration requires wiping and reinstalling the machine.
+!!! Danger
+    Don't change the `disko.nix` after the machine is installed for the first time, unless you really know what you are doing.
+    Changing disko configuration requires wiping and reinstalling the machine.
 
 ## Deploy the machine
 
-**Finally deployment time!**
+**Finally deployment time!** 
+
+This command is destructive and will format your disk and install NixOS on it! It is equivalent to appending `--phases kexec,disko,install,reboot`. 
 
-This command is destructive and will format your disk and install NixOS on it!
-It is equivalent to appending `--phases kexec,disko,install,reboot`.
 
 ```bash
 clan machines install [MACHINE] --target-host root@<IP>
 ```
+
+

docs/site/guides/getting-started/create-installer.md

@@ -1,27 +1,15 @@
 # USB Installer Image for Physical Machines
 
-To install Clan on physical machines, you need to use our custom installer
-image. This is necessary for proper installation and operation.
+To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation.
 
-!!! note "Deploying to a Virtual Machine?" If you're deploying to a virtual
-machine (VM), you can skip this section and go directly to the
-[Deploy Virtual Machine](./hardware-report-virtual.md) step. In this scenario,
-we automatically use
-[nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the
-kernel during runtime.
+!!! note "Deploying to a Virtual Machine?"
+    If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](./hardware-report-virtual.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
 
-??? info "Why nixos-anywhere Doesn't Work on Physical Hardware?" nixos-anywhere
-relies on [kexec](https://wiki.archlinux.org/title/Kexec) to replace the running
-kernel with our custom one. This method often has compatibility issues with real
-hardware, especially systems with dedicated graphics cards like laptops and
-servers, leading to crashes and black screens.
+??? info "Why nixos-anywhere Doesn't Work on Physical Hardware?"
+    nixos-anywhere relies on [kexec](https://wiki.archlinux.org/title/Kexec) to replace the running kernel with our custom one. This method often has compatibility issues with real hardware, especially systems with dedicated graphics cards like laptops and servers, leading to crashes and black screens.
 
-??? info "Reasons for a Custom Install Image" Our custom install images are
-built to include essential tools like
-[nixos-facter](https://github.com/nix-community/nixos-facter) and support for
-[ZFS](https://wiki.archlinux.org/title/ZFS). They're also optimized to run on
-systems with as little as 1 GB of RAM, ensuring efficient performance even on
-lower-end hardware.
+??? info "Reasons for a Custom Install Image"
+    Our custom install images are built to include essential tools like [nixos-facter](https://github.com/nix-community/nixos-facter) and support for [ZFS](https://wiki.archlinux.org/title/ZFS). They're also optimized to run on systems with as little as 1 GB of RAM, ensuring efficient performance even on lower-end hardware.
 
 ## Prerequisites
 
@@ -34,24 +22,23 @@ lower-end hardware.
 
 2. Identify your flash drive with `lsblk`:
 
-   ```shellSession
-   lsblk
-   ```
+    ```shellSession
+    lsblk
+    ```
 
-   ```{.shellSession hl_lines="2" .no-copy}
-   NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
-   sdb                                             8:0    1 117,2G  0 disk
-   └─sdb1                                          8:1    1 117,2G  0 part  /run/media/qubasa/INTENSO
-   nvme0n1                                       259:0    0   1,8T  0 disk
-   ├─nvme0n1p1                                   259:1    0   512M  0 part  /boot
-   └─nvme0n1p2                                   259:2    0   1,8T  0 part
-     └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0    0   1,8T  0 crypt /nix/store
-   ```
+    ```{.shellSession hl_lines="2" .no-copy}
+    NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
+    sdb                                             8:0    1 117,2G  0 disk
+    └─sdb1                                          8:1    1 117,2G  0 part  /run/media/qubasa/INTENSO
+    nvme0n1                                       259:0    0   1,8T  0 disk
+    ├─nvme0n1p1                                   259:1    0   512M  0 part  /boot
+    └─nvme0n1p2                                   259:2    0   1,8T  0 part
+      └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0    0   1,8T  0 crypt /nix/store
+    ```
 
-   !!! Info "In this case the USB device is `sdb`"
+    !!! Info "In this case the USB device is `sdb`"
 
-3. Ensure all partitions on the drive are unmounted. Replace `sdb1` in the
-   command below with your device identifier (like `sdc1`, etc.):
+3. Ensure all partitions on the drive are unmounted. Replace `sdb1` in the command below with your device identifier (like `sdc1`, etc.):
 
 ```shellSession
 sudo umount /dev/sdb1
@@ -59,122 +46,117 @@ sudo umount /dev/sdb1
 
 ## Installer
 
-=== "**Linux OS**" **Create a Custom Installer**
+=== "**Linux OS**"
+    **Create a Custom Installer**
 
-````
-We recommend to build your own installer because of the following reasons:
+    We recommend to build your own installer because of the following reasons:
 
-- Include your ssh public keys into the image that allows passwordless ssh connection later on.
-- Set your preferred language and keymap
+    - Include your ssh public keys into the image that allows passwordless ssh connection later on.
+    - Set your preferred language and keymap
 
-```bash
-clan flash write --flake https://git.clan.lol/clan/clan-core/archive/main.tar.gz \
-  --ssh-pubkey $HOME/.ssh/id_ed25519.pub \
-  --keymap us \
-  --language en_US.UTF-8 \
-  --disk main /dev/sd<X> \
-  flash-installer
-```
-!!! Note
-    Replace `$HOME/.ssh/id_ed25519.pub` with a path to your SSH public key.
-    Replace `/dev/sd<X>` with the drive path you want to flash
-
-!!! Danger "Specifying the wrong device can lead to unrecoverable data loss."
-
-    The `clan flash` utility will erase the disk. Make sure to specify the correct device
-
-- **SSH-Pubkey Option**
-
-    To add an ssh public key into the installer image append the option:
+    ```bash
+    clan flash write --flake https://git.clan.lol/clan/clan-core/archive/main.tar.gz \
+      --ssh-pubkey $HOME/.ssh/id_ed25519.pub \
+      --keymap us \
+      --language en_US.UTF-8 \
+      --disk main /dev/sd<X> \
+      flash-installer
     ```
-    --ssh-pubkey <pubkey_path>
-    ```
-    If you do not have an ssh key yet, you can generate one with `ssh-keygen -t ed25519` command.
-    This ssh key will be installed into the root user.
+    !!! Note
+        Replace `$HOME/.ssh/id_ed25519.pub` with a path to your SSH public key.
+        Replace `/dev/sd<X>` with the drive path you want to flash
 
-- **Connect to the installer**
+    !!! Danger "Specifying the wrong device can lead to unrecoverable data loss."
 
-    On boot, the installer will display on-screen the IP address it received from the network.
-    If you need to configure Wi-Fi first, refer to the next section.
-    If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the `flash-installer.local` address.
+        The `clan flash` utility will erase the disk. Make sure to specify the correct device
 
-- **List Keymaps**
+    - **SSH-Pubkey Option**
 
-    You can get a list of all keymaps with the following command:
-    ```
-    clan flash list keymaps
+        To add an ssh public key into the installer image append the option:
+        ```
+        --ssh-pubkey <pubkey_path>
+        ```
+        If you do not have an ssh key yet, you can generate one with `ssh-keygen -t ed25519` command.
+        This ssh key will be installed into the root user.
+
+    - **Connect to the installer**
+
+        On boot, the installer will display on-screen the IP address it received from the network.
+        If you need to configure Wi-Fi first, refer to the next section.
+        If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the `flash-installer.local` address.
+
+    - **List Keymaps**
+
+        You can get a list of all keymaps with the following command:
+        ```
+        clan flash list keymaps
+        ```
+
+    - **List Languages**
+
+        You can get a list of all languages with the following command:
+        ```
+        clan flash list languages
+        ```
+
+=== "**Other OS**"
+    **Download Generic Installer**
+
+    For x86_64:
+
+    ```shellSession
+    wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso
     ```
 
-- **List Languages**
+    For generic arm64 / aarch64 (probably does not work on raspberry pi...)
 
-    You can get a list of all languages with the following command:
+    ```shellSession
+    wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-aarch64-linux.iso
     ```
-    clan flash list languages
+
+    !!! Note
+        If you don't have `wget` installed, you can use `curl --progress-bar -OL <url>` instead.
+
+    ## Flash the Installer to the USB Drive
+
+    !!! Danger "Specifying the wrong device can lead to unrecoverable data loss."
+
+        The `dd` utility will erase the disk. Make sure to specify the correct device (`of=...`)
+
+        For example if the USB device is `sdb` use `of=/dev/sdb` (on macOS it will look more like /dev/disk1)
+
+    On Linux, you can use the `lsblk` utility to identify the correct disko
+
+    ```
+    lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
     ```
-````
 
-=== "**Other OS**" **Download Generic Installer**
+    On macos use `diskutil`:
 
-````
-For x86_64:
+    ```
+    diskutil list
+    ```
 
-```shellSession
-wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso
-```
+    Use the `dd` utility to write the NixOS installer image to your USB drive.
+    Replace `/dev/sd<X>` with your external drive from above.
 
-For generic arm64 / aarch64 (probably does not work on raspberry pi...)
+    ```shellSession
+    sudo dd bs=4M conv=fsync status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd<X>
+    ```
 
-```shellSession
-wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-aarch64-linux.iso
-```
+    - **Connect to the installer
 
-!!! Note
-    If you don't have `wget` installed, you can use `curl --progress-bar -OL <url>` instead.
-
-## Flash the Installer to the USB Drive
-
-!!! Danger "Specifying the wrong device can lead to unrecoverable data loss."
-
-    The `dd` utility will erase the disk. Make sure to specify the correct device (`of=...`)
-
-    For example if the USB device is `sdb` use `of=/dev/sdb` (on macOS it will look more like /dev/disk1)
-
-On Linux, you can use the `lsblk` utility to identify the correct disko
-
-```
-lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-```
-
-On macos use `diskutil`:
-
-```
-diskutil list
-```
-
-Use the `dd` utility to write the NixOS installer image to your USB drive.
-Replace `/dev/sd<X>` with your external drive from above.
-
-```shellSession
-sudo dd bs=4M conv=fsync status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd<X>
-```
-
-- **Connect to the installer
-
-  On boot, the installer will display on-screen the IP address it received from the network.
-  If you need to configure Wi-Fi first, refer to the next section.
-  If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the `nixos-installer.local` address.
-````
+      On boot, the installer will display on-screen the IP address it received from the network.
+      If you need to configure Wi-Fi first, refer to the next section.
+      If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the `nixos-installer.local` address.
 
 ## Boot From USB Stick
 
-- To use, boot from the Clan USB drive with **secure boot turned off**. For step
-  by step instructions go to
-  [Disabling Secure Boot](../../guides/secure-boot.md)
+- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../../guides/secure-boot.md)
 
 ## (Optional) Connect to Wifi Manually
 
-If you don't have access via LAN the Installer offers support for connecting via
-Wifi.
+If you don't have access via LAN the Installer offers support for connecting via Wifi.
 
 ```shellSession
 iwctl
@@ -215,7 +197,7 @@ IPv4 address          192.168.188.50 (Your new local ip)
 
 Press ++ctrl+d++ to exit `IWD`.
 
-!!! Important Press ++ctrl+d++ **again** to update the displayed QR code and
-connection information.
+!!! Important
+    Press ++ctrl+d++ **again** to update the displayed QR code and connection information.
 
 You're all set up

docs/site/guides/getting-started/flake-check.md

@@ -1,13 +1,9 @@
 ### Generate Facts and Vars
 
-Typically, this step is handled automatically when a machine is deployed.
-However, to enable the use of `nix flake check` with your configuration, it must
-be completed manually beforehand.
+Typically, this step is handled automatically when a machine is deployed. However, to enable the use of `nix flake check` with your configuration, it must be completed manually beforehand.
 
-Currently, generating all the necessary facts requires two separate commands.
-This is due to the coexistence of two parallel secret management solutions: the
-newer, recommended version (`clan vars`) and the older version (`clan facts`)
-that we are slowly phasing out.
+Currently, generating all the necessary facts requires two separate commands. This is due to the coexistence of two parallel secret management solutions:
+the newer, recommended version (`clan vars`) and the older version (`clan facts`) that we are slowly phasing out.
 
 To generate both facts and vars, execute the following commands:
 
@@ -15,6 +11,7 @@ To generate both facts and vars, execute the following commands:
 clan facts generate && clan vars generate
 ```
 
+
 ### Check Configuration
 
 Validate your configuration by running:
@@ -23,11 +20,9 @@ Validate your configuration by running:
 nix flake check
 ```
 
-This command helps ensure that your system configuration is correct and free
-from errors.
+This command helps ensure that your system configuration is correct and free from errors.
 
 !!! Tip
 
-```
-You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase.
-```
+    You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase.
+

docs/site/guides/getting-started/hardware-report-physical.md

@@ -1,29 +1,22 @@
 # Installing a Physical Machine
 
-Now that you have created a machine, added some services, and set up secrets,
-this guide will walk you through how to deploy it.
+Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
+
 
 ### Step 0. Prerequisites
-
 - [x] RAM > 2GB
-- [x] **Two Computers**: You need one computer that you're getting ready (we'll
-  call this the Target Computer) and another one to set it up from (we'll call
-  this the Setup Computer). Make sure both can talk to each other over the
-  network using SSH.
-- [x] **Machine configuration**: See our basic
-  [adding and configuring machine guide](./add-machines.md)
-- [x] **Initialized secrets**: See [secrets](../secrets.md) for how to
-  initialize your secrets.
+- [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
+- [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
+- [x] **Initialized secrets**: See [secrets](../secrets.md) for how to initialize your secrets.
 - [x] **USB Flash Drive**: See [Clan Installer](./create-installer.md)
 
-### Image Installer
 
+### Image Installer
 This method makes use of the [image installers](./create-installer.md).
 
-The installer will randomly generate a password and local addresses on boot,
-then run a SSH server with these preconfigured. The installer shows its
-deployment relevant information in two formats, a text form, as well as a QR
-code.
+The installer will randomly generate a password and local addresses on boot, then run a SSH server with these preconfigured.
+The installer shows its deployment relevant information in two formats, a text form, as well as a QR code.
+
 
 This is an example of the booted installer.
 
@@ -57,70 +50,65 @@ This is an example of the booted installer.
 └─────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-1. This is not an actual QR code, because it is displayed rather poorly on text
-   sites. This would be the actual content of this specific QR code prettified:
+1.  This is not an actual QR code, because it is displayed rather poorly on text sites.
+    This would be the actual content of this specific QR code prettified:
+    ```json
+    {
+        "pass": "cheesy-capital-unwell",
+        "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion",
+        "addrs": [
+        "2001:9e8:347:ca00:21e:6ff:fe45:3c92"
+        ]
+    }
+    ```
 
-   ```json
-   {
-       "pass": "cheesy-capital-unwell",
-       "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion",
-       "addrs": [
-       "2001:9e8:347:ca00:21e:6ff:fe45:3c92"
-       ]
-   }
-   ```
+    To generate the actual QR code, that would be displayed use:
+    ```shellSession
+    echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8
+    ```
+2.  The root password for the installer medium.
+    This password is autogenerated and meant to be easily typeable.
+3.  See how to connect the installer medium to wlan [here](./create-installer.md).
 
-   To generate the actual QR code, that would be displayed use:
-
-   ```shellSession
-   echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8
-   ```
-
-2. The root password for the installer medium. This password is autogenerated
-   and meant to be easily typeable.
-
-3. See how to connect the installer medium to wlan
-   [here](./create-installer.md).
-
-!!!tip For easy sharing of deployment information via QR code, we highly
-recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).
+!!!tip
+    For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).
 
 There are two ways to deploy your machine:
 
-=== "Password" ### Generating a Hardware Report
 
-````
-The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel.
+=== "Password"
+    ### Generating a Hardware Report
+
+    The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel.
 
 
-```terminal
-clan machines install [MACHINE] \
-    --update-hardware-config nixos-facter \
-    --phases kexec \
-    --target-host root@192.168.178.169
-```
-````
+    ```terminal
+    clan machines install [MACHINE] \
+        --update-hardware-config nixos-facter \
+        --phases kexec \
+        --target-host root@192.168.178.169
+    ```
 
-=== "QR Code" ### Generating a Hardware Report
+=== "QR Code"
+    ### Generating a Hardware Report
 
-````
-The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel.
+    The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel.
 
-#### Using a JSON String or File Path
-Copy the JSON string contained in the QR Code and provide its path or paste it directly:
-```terminal
-clan machines install [MACHINE] --json [JSON] \
-    --update-hardware-config nixos-facter \
-    --phases kexec
-```
+    #### Using a JSON String or File Path
+    Copy the JSON string contained in the QR Code and provide its path or paste it directly:
+    ```terminal
+    clan machines install [MACHINE] --json [JSON] \
+        --update-hardware-config nixos-facter \
+        --phases kexec
+    ```
+
+    #### Using an Image Containing the QR Code
+    Provide the path to an image file containing the QR code displayed by the installer:
+    ```terminal
+    clan machines install [MACHINE] --png [PATH] \
+        --update-hardware-config nixos-facter \
+        --phases kexec
+    ```
 
-#### Using an Image Containing the QR Code
-Provide the path to an image file containing the QR code displayed by the installer:
-```terminal
-clan machines install [MACHINE] --png [PATH] \
-    --update-hardware-config nixos-facter \
-    --phases kexec
-```
-````
 
 If you are using our template `[MACHINE]` would be `jon`

docs/site/guides/getting-started/hardware-report-virtual.md

@@ -1,29 +1,23 @@
 # Generate a VM Hardware Report
 
-Now that you have created a machine, added some services, and set up secrets,
-this guide will walk you through how to deploy it.
+Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
+
 
 ## Prerequisites
-
 - [x] RAM > 2GB
-- [x] **Two Computers**: You need one computer that you're getting ready (we'll
-  call this the Target Computer) and another one to set it up from (we'll call
-  this the Setup Computer). Make sure both can talk to each other over the
-  network using SSH.
-- [x] **Machine configuration**: See our basic
-  [adding and configuring machine guide](./add-machines.md)
+- [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
+- [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
+
 
 Clan supports any cloud machine if it is reachable via SSH and supports `kexec`.
 
-??? tip "NixOS can cause strange issues when booting in certain cloud
-environments." If on Linode: Make sure that the system uses "Direct Disk boot
-kernel" (found in the configuration panel)
 
-The following command will generate a hardware report with
-[nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back
-into your machine folder. The `--phases kexec` flag makes sure we are not yet
-formatting anything, instead if the target system is not a NixOS machine it will
-use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel.
+??? tip "NixOS can cause strange issues when booting in certain cloud environments."
+    If on Linode: Make sure that the system uses "Direct Disk boot kernel" (found in the configuration panel)
+
+
+The following command will generate a hardware report with [nixos-facter](https://github.com/nix-community/nixos-facter) and writes it back into your machine folder. The `--phases kexec` flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use [kexec](https://wiki.archlinux.org/title/Kexec) to switch to a NixOS kernel.
+
 
 ```terminal
 clan machines install [MACHINE] \
@@ -32,7 +26,5 @@ clan machines install [MACHINE] \
   --target-host myuser@<IP>
 ```
 
-!!! Warning After running the above command, be aware that the SSH login user
-changes from `myuser` to `root`. For subsequent SSH connections to the target
-machine, use `root` as the login user. This change occurs because the system
-switches to the NixOS kernel using `kexec`.
+!!! Warning
+    After running the above command, be aware that the SSH login user changes from `myuser` to `root`. For subsequent SSH connections to the target machine, use `root` as the login user. This change occurs because the system switches to the NixOS kernel using `kexec`.

docs/site/guides/getting-started/index.md

@@ -1,141 +1,110 @@
 # :material-clock-fast: Getting Started
 
-Ready to manage your fleet of machines?
+Ready to create your own Clan and manage a fleet of machines? Follow these simple steps to get started.
 
-We will create a declarative infrastructure using **clan**, **git**, and **nix
-flakes**.
+This guide walks your through setting up your own declarative infrastructure using clan, git and flakes. By the end of this, you will have one or more machines integrated and installed. You can then import your existing NixOS configuration into this setup if you wish.
 
-You'll finish with a centrally managed fleet, ready to import your existing
-NixOS configuration.
+The following steps are meant to be executed on the machine on which to administer the infrastructure.
+
+In order to get started you should have at least one machine with either physical or ssh access available as an installation target. Your local machine can also be used as an installation target if it is already running NixOS.
 
 ## Prerequisites
 
-Make sure you have the following:
+=== "**Linux**"
 
-- 💻 **Administration Machine**: Run the setup commands from this machine.
+    Clan requires Nix to be installed on your system. Run the following command to install Nix:
 
-- 🛠️ **Nix**: The Nix package manager, installed on your administration machine.
+    ```shellSession
+    curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+    ```
 
-  ??? info "**How to install Nix (Linux / MacOS / NixOS)**"
+    If you have previously installed Nix, make sure `experimental-features = nix-command flakes` is present in `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`. If this is not the case, please add it to `~/.config/nix/nix.conf`.
 
-  ````
-    **On Linux or macOS:**
+=== "**NixOS**"
 
-    1.  Run the recommended installer:
-        ```shellSession
-        curl --proto '=https' --tlsv1.2 -sSf -L [https://install.determinate.systems/nix](https://install.determinate.systems/nix) | sh -s -- install
-        ```
+    If you run NixOS the `nix` binary is already installed.
 
-    2.  After installation, ensure flakes are enabled by adding this line to `~/.config/nix/nix.conf`:
-        ```
-        experimental-features = nix-command flakes
-        ```
-
-    **On NixOS:**
-
-    Nix is already installed. You only need to enable flakes for your user in your `configuration.nix`:
+    You will also need to enable the `nix-command` and `flakes` experimental features in your `configuration.nix`:
 
     ```nix
-    {
-      nix.settings.experimental-features = [ "nix-command" "flakes" ];
-    }
+    { nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
     ```
-    Then, run `nixos-rebuild switch` to apply the changes.
-  ````
 
-- 🎯 **Target Machine(s)**: A remote machine with SSH, or your local machine (if
-  NixOS).
+=== "**macOS**"
 
-## Create a New Clan
+    Clan requires Nix to be installed on your system. Run the following command to install Nix:
 
-1. Navigate to your desired directory:
+    ```shellSession
+    curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+    ```
 
-   ```shellSession
-   cd <your-directory>
-   ```
+    If you have previously installed Nix, make sure `experimental-features = nix-command flakes` is present in `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`. If this is not the case, please add it to `~/.config/nix/nix.conf`.
 
-2. Create a new clan flake:
+## Create a new clan
 
-   **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
-   ```
-
-3. Enter a **name** in the prompt:
-
-   ```terminalSession
-   Enter a name for the new clan: my-clan
-   ```
-
-## Project Structure
-
-Your new directory, `my-clan`, should contain the following structure:
-
-```
-my-clan/
-├── clan.nix
-├── flake.lock
-├── flake.nix
-├── modules/
-└── sops/
-```
-
-!!! note "Templates" This is the structure for the `default` template.
-
-```
-Use `clan templates list` and `clan templates --help` for available templates & more. Keep in mind that the exact files may change as templates evolve.
-```
-
-## Activate the Environment
-
-To get started, `cd` into your new project directory.
+Initialize a new clan flake
 
 ```shellSession
-cd my-clan
+nix run https://git.clan.lol/clan/clan-core/archive/main.tar.gz#clan-cli --refresh -- flakes create
 ```
 
-Now, activate the environment using one of the following methods.
+This should prompt for a *name*:
 
-=== "Automatic (direnv, recommended)" **Prerequisite**: You must have
-[nix-direnv](https://github.com/nix-community/nix-direnv) installed.
-
-````
-Run `direnv allow` to automatically load the environment whenever you enter this directory.
-```shellSession
-direnv allow
+```terminalSession
+Enter a name for the new clan: my-clan
 ```
-````
 
-=== "Manual (nix develop)" Run nix develop to load the environment for your
-current shell session.
+Enter a *name*, confirm with *enter*. A directory with that name will be created and initialized.
 
-````
-```shellSession
-nix develop
+!!! Note
+    This command uses the `default` template
+
+    See `clan templates list` and the `--help` reference for how to use other templates.
+
+## Explore the Project Structure
+
+Take a look at all project files:
+For example, you might see something like:
+
+```{ .console .no-copy }
+$ cd my-clan
+$ ls
+clan.nix  flake.lock  flake.nix  modules  sops
 ```
-````
 
-## Verify the Setup
 
-Once your environment is active, verify that the clan command is available by
-running:
+
+Don’t worry if your output looks different — Clan templates evolve over time.
+
+To interact with your newly created clan the you need to load the `clan` cli-package it into your environment by running:
+
+=== "Automatic (direnv, recommended)"
+    - prerequisite: [install nix-direnv](https://github.com/nix-community/nix-direnv)
+
+    ```shellSession
+    direnv allow
+    ```
+
+=== "Manual (nix develop)"
+
+    ```shellSession
+    nix develop
+    ```
+
+verify that you can run `clan` commands:
 
 ```shellSession
 clan show
 ```
 
-You should see the default metadata for your new clan:
+You should see something like this:
 
 ```shellSession
 Name: __CHANGE_ME__
 Description: None
 ```
 
-This confirms your setup is working correctly.
-
-You can now change the default name by editing the `meta.name` field in your
-`clan.nix` file.
+To change the name of your clan edit `meta.name` in the `clan.nix` or `flake.nix` file
 
 ```{.nix title="clan.nix" hl_lines="3"}
 {
@@ -146,3 +115,4 @@ You can now change the default name by editing the `meta.name` field in your
   # elided
 }
 ```
+

docs/site/guides/getting-started/update.md

@@ -1,12 +1,12 @@
+
 # Update Your Machines
 
-Clan CLI enables you to remotely update your machines over SSH. This requires
-setting up a target address for each target machine.
+Clan CLI enables you to remotely update your machines over SSH. This requires setting up a target address for each target machine.
 
 ### Setting `targetHost`
 
-In your Nix files, set the `targetHost` to the reachable IP address of your new
-machine. This eliminates the need to specify `--target-host` with every command.
+In your Nix files, set the `targetHost` to the reachable IP address of your new machine. This eliminates the need to specify `--target-host` with every command.
+
 
 ```{.nix title="clan.nix" hl_lines="9"}
 {
@@ -23,15 +23,16 @@ inventory.machines = {
 # [...]
 }
 ```
-
 The use of `root@` in the target address implies SSH access as the `root` user.
 Ensure that the root login is secured and only used when necessary.
 
+
 ### Setting a Build Host
 
-If the machine does not have enough resources to run the NixOS evaluation or
-build itself, it is also possible to specify a build host instead. During an
-update, the cli will ssh into the build host and run `nixos-rebuild` from there.
+If the machine does not have enough resources to run the NixOS evaluation or build itself,
+it is also possible to specify a build host instead.
+During an update, the cli will ssh into the build host and run `nixos-rebuild` from there.
+
 
 ```{.nix hl_lines="5" .no-copy}
 buildClan {
@@ -54,10 +55,10 @@ clan machines update jon --build-host root@192.168.1.10
 clan machines update jon --build-host local
 ```
 
-!!! Note Make sure that the CPU architecture is the same for the buildHost as
-for the targetHost. Example: If you want to deploy to a macOS machine, your
-architecture is an ARM64-Darwin, that means you need a second macOS machine to
-build it.
+!!! Note
+    Make sure that the CPU architecture is the same for the buildHost as for the targetHost.
+    Example:
+        If you want to deploy to a macOS machine, your architecture is an ARM64-Darwin, that means you need a second macOS machine to build it.
 
 ### Updating Machine Configurations
 
@@ -67,18 +68,17 @@ Execute the following command to update the specified machine:
 clan machines update jon
 ```
 
-You can also update all configured machines simultaneously by omitting the
-machine name:
+You can also update all configured machines simultaneously by omitting the machine name:
 
 ```bash
 clan machines update
 ```
 
+
 ### Excluding a machine from `clan machine update`
 
-To exclude machines from being updated when running `clan machines update`
-without any machines specified, one can set the
-`clan.deployment.requireExplicitUpdate` option to true:
+To exclude machines from being updated when running `clan machines update` without any machines specified,
+one can set the `clan.deployment.requireExplicitUpdate` option to true:
 
 ```{.nix hl_lines="5" .no-copy}
 buildClan {
@@ -91,22 +91,19 @@ buildClan {
 };
 ```
 
-This is useful for machines that are not always online or are not part of the
-regular update cycle.
+This is useful for machines that are not always online or are not part of the regular update cycle.
 
 ### Uploading Flake Inputs
 
-When updating remote machines, flake inputs are usually fetched by the build
-host. However, if your flake inputs require authentication (e.g., private
-repositories), you can use the `--upload-inputs` flag to upload all inputs from
-your local machine:
+When updating remote machines, flake inputs are usually fetched by the build host.
+However, if your flake inputs require authentication (e.g., private repositories),
+you can use the `--upload-inputs` flag to upload all inputs from your local machine:
 
 ```bash
 clan machines update jon --upload-inputs
 ```
 
 This is particularly useful when:
-
 - Your flake references private Git repositories
 - Authentication credentials are only available on your local machine
 - The build host doesn't have access to certain network resources

docs/site/guides/macos.md

@@ -6,14 +6,12 @@ This guide explains how to manage macOS machines using Clan.
 
 Currently, Clan supports the following features for macOS:
 
-- `clan machines update` for existing
-  [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations
+- `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations
 - Support for [vars](../concepts/generators.md)
 
 ## Add Your Machine to Your Clan Flake
 
-In this example, we'll name the machine `yourmachine`. Replace this with your
-preferred machine name.
+In this example, we'll name the machine `yourmachine`. Replace this with your preferred machine name.
 
 === "**If using clan-core.lib.clan**"
 
@@ -39,8 +37,7 @@ clan-core.lib.clan {
 
 ## Add a `configuration.nix` for Your Machine
 
-Create the file `./machines/yourmachine/configuration.nix` with the following
-content (replace `yourmachine` with your chosen machine name):
+Create the file `./machines/yourmachine/configuration.nix` with the following content (replace `yourmachine` with your chosen machine name):
 
 ```nix
 {
@@ -63,13 +60,12 @@ Replace `yourmachine` with your chosen machine name.
 
 ## Install Nix
 
-Install Nix on your macOS machine using one of the methods described in the
-[nix-darwin prerequisites](https://github.com/nix-darwin/nix-darwin?tab=readme-ov-file#prerequisites).
+Install Nix on your macOS machine using one of the methods described in the [nix-darwin prerequisites](https://github.com/nix-darwin/nix-darwin?tab=readme-ov-file#prerequisites).
+
 
 ## Install nix-darwin
 
-Upload your Clan flake to the macOS machine. Then, from within your flake
-directory, run:
+Upload your Clan flake to the macOS machine. Then, from within your flake directory, run:
 
 ```sh
 sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#yourmachine

docs/site/guides/mesh-vpn.md

@@ -1,12 +1,12 @@
+
 This guide provides detailed instructions for configuring
-[ZeroTier VPN](https://zerotier.com) within Clan. Follow the outlined steps to
-set up a machine as a VPN controller (`<CONTROLLER>`) and to include a new
-machine into the VPN.
+[ZeroTier VPN](https://zerotier.com) within Clan. Follow the
+outlined steps to set up a machine as a VPN controller (`<CONTROLLER>`) and to
+include a new machine into the VPN.
 
 ## Concept
 
-By default all machines within one clan are connected via a chosen network
-technology.
+By default all machines within one clan are connected via a chosen network technology.
 
 ```{.no-copy}
 Clan
@@ -15,22 +15,19 @@ Clan
     Node B
 ```
 
-This guide shows you how to configure `zerotier` through clan's `Inventory`
-System.
+This guide shows you how to configure `zerotier` through clan's `Inventory` System.
 
 ## The Controller
 
-The controller is the initial entrypoint for new machines into the vpn. It will
-sign the id's of new machines. Once id's are signed, the controller's continuous
-operation is not essential. A good controller choice is nevertheless a machine
-that can always be reached for updates - so that new peers can be added to the
-network.
+The controller is the initial entrypoint for new machines into the vpn.
+It will sign the id's of new machines.
+Once id's are signed, the controller's continuous operation is not essential.
+A good controller choice is nevertheless a machine that can always be reached for updates - so that new peers can be added to the network.
 
 For the purpose of this guide we have two machines:
 
 - The `controller` machine, which will be the zerotier controller.
-- The `new_machine` machine, which is the machine we want to add to the vpn
-  network.
+- The `new_machine` machine, which is the machine we want to add to the vpn network.
 
 ## Configure the Service
 
@@ -102,15 +99,12 @@ The status should be "ONLINE":
 
 ## Further
 
-Currently you can only use **Zerotier** as networking technology because this is
-the first network stack we aim to support. In the future we plan to add
-additional network technologies like tinc, head/tailscale, yggdrassil and
-mycelium.
+Currently you can only use **Zerotier** as networking technology because this is the first network stack we aim to support.
+In the future we plan to add additional network technologies like tinc, head/tailscale, yggdrassil and mycelium.
 
-We chose zerotier because in our tests it was a straight forwards solution to
-bootstrap. It allows you to selfhost a controller and the controller doesn't
-need to be globally reachable. Which made it a good fit for starting the
-project.
+We chose zerotier because in our tests it was a straight forwards solution to bootstrap.
+It allows you to selfhost a controller and the controller doesn't need to be globally reachable.
+Which made it a good fit for starting the project.
 
 ## Debugging
 
@@ -140,20 +134,16 @@ $ sudo zerotier-cli info
 
 === "with ZerotierIP"
 
-````
-  ```bash
-  $ sudo zerotier-members allow --member-ip <IP>
-  ```
+      ```bash
+      $ sudo zerotier-members allow --member-ip <IP>
+      ```
 
-  Substitute `<IP>` with the ZeroTier IP obtained previously.
-````
+      Substitute `<IP>` with the ZeroTier IP obtained previously.
 
 === "with ZerotierID"
 
-````
-  ```bash
-  $ sudo zerotier-members allow <ID>
-  ```
+      ```bash
+      $ sudo zerotier-members allow <ID>
+      ```
 
-  Substitute `<ID>` with the ZeroTier ID obtained previously.
-````
+      Substitute `<ID>` with the ZeroTier ID obtained previously.

docs/site/guides/migrations/disk-id.md

@@ -1,8 +1,6 @@
 # Migrate disko config from `clanModules.disk-id`
 
-If you previously bootstrapped a machine's disk using `clanModules.disk-id`, you
-should now migrate to a standalone, self-contained disko configuration. This
-ensures long-term stability and avoids reliance on dynamic values from Clan.
+If you previously bootstrapped a machine's disk using `clanModules.disk-id`, you should now migrate to a standalone, self-contained disko configuration. This ensures long-term stability and avoids reliance on dynamic values from Clan.
 
 If your `disko.nix` currently looks something like this:
 
@@ -51,8 +49,8 @@ Run the following command to retrieve the generated disk ID for your machine:
 clan vars list <machineName>
 ```
 
-Which should print the generated `disk-id/diskId` value in clear text You should
-see output like:
+Which should print the generated `disk-id/diskId` value in clear text
+You should see output like:
 
 ```shellSession
 disk-id/diskId: fcef30a749f8451d8f60c46e1ead726f
@@ -70,8 +68,7 @@ We are going to make three changes:
 
 - Remove `let in, imports, {lib,clan-core,config, ...}:` to isolate the file.
 - Replace `suffix` with the actual disk-id
-- Move `disko.devices.disk.main.device` from `flake.nix` or `configuration.nix`
-  into this file.
+- Move `disko.devices.disk.main.device` from `flake.nix` or `configuration.nix` into this file.
 
 ```{.nix title="disko.nix" hl_lines="7-9 11-14"}
 {
@@ -96,8 +93,6 @@ We are going to make three changes:
 }
 ```
 
-These steps are only needed for existing configurations that depend on the
-`diskId` module.
+These steps are only needed for existing configurations that depend on the `diskId` module.
 
-For newer machines clan offers simple *disk templates* via its
-[templates cli](../../reference/cli/templates.md)
+For newer machines clan offers simple *disk templates* via its [templates cli](../../reference/cli/templates.md)

docs/site/guides/migrations/migrate-inventory-services.md

@@ -1,23 +1,21 @@
 # Migrating from using `clanModules` to `clanServices`
 
-**Audience**: This is a guide for **people using `clanModules`**. If you are a
-**module author** and need to migrate your modules please consult our **new**
-[clanServices authoring guide](../../guides/services/community.md)
+**Audience**: This is a guide for **people using `clanModules`**.
+If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../../guides/services/community.md)
 
 ## What's Changing?
 
-Clan is transitioning from the legacy `clanModules` system to the `clanServices`
-system. This guide will help you migrate your service definitions from the old
-format (`inventory.services`) to the new format (`inventory.instances`).
+Clan is transitioning from the legacy `clanModules` system to the `clanServices` system. This guide will help you migrate your service definitions from the old format (`inventory.services`) to the new format (`inventory.instances`).
 
-| Feature | `clanModules` (Old) | `clanServices` (New) | | ---------------- |
--------------------------- | ----------------------- | | Module Class |
-`"nixos"` | `"clan.service"` | | Inventory Key | `services` | `instances` | |
-Module Source | Static | Composable via flakes | | Custom Settings | Loosely
-structured | Strongly typed per-role | | Migration Status | Deprecated (to be
-removed) | ✅ Preferred |
+| Feature          | `clanModules` (Old)        | `clanServices` (New)    |
+| ---------------- | -------------------------- | ----------------------- |
+| Module Class     | `"nixos"`                  | `"clan.service"`        |
+| Inventory Key    | `services`                 | `instances`             |
+| Module Source    | Static                     | Composable via flakes   |
+| Custom Settings  | Loosely structured         | Strongly typed per-role |
+| Migration Status | Deprecated (to be removed) | ✅ Preferred             |
 
-______________________________________________________________________
+---
 
 ## Before: Old `services` Definition
 
@@ -68,7 +66,7 @@ services = {
 };
 ```
 
-______________________________________________________________________
+---
 
 ## ✅ After: New `instances` Definition with `clanServices`
 
@@ -153,14 +151,13 @@ instances = {
 };
 ```
 
-______________________________________________________________________
+---
 
 ## Steps to Migrate
 
 ### Move `services` entries to `instances`
 
-Check if a service that you use has been migrated
-[In our reference](../../reference/clanServices/index.md)
+Check if a service that you use has been migrated [In our reference](../../reference/clanServices/index.md)
 
 In your inventory, move it from:
 
@@ -174,10 +171,9 @@ to:
 instances = { ... };
 ```
 
-Each nested service-instance-pair becomes a flat key, like
-`borgbackup.simple → borgbackup-simple`.
+Each nested service-instance-pair becomes a flat key, like `borgbackup.simple → borgbackup-simple`.
 
-______________________________________________________________________
+---
 
 ### Add `module.name` and `module.input`
 
@@ -198,15 +194,15 @@ inputs.clan-core.url = "github:clan/clan-core";
 
 Then refer to it as `input = "clan-core"`.
 
-______________________________________________________________________
+---
 
 ### Move role and machine config under `roles`
 
 In the new system:
 
-- Use `roles.<role>.machines.<hostname>.settings` for machine-specific config.
-- Use `roles.<role>.settings` for role-wide config.
-- Remove: `.config` as a top-level attribute is removed.
+* Use `roles.<role>.machines.<hostname>.settings` for machine-specific config.
+* Use `roles.<role>.settings` for role-wide config.
+* Remove: `.config` as a top-level attribute is removed.
 
 Example:
 
@@ -218,8 +214,7 @@ roles.default.machines."test-inventory-machine".settings = {
 
 ### Important Type Changes
 
-The new `instances` format uses **attribute sets** instead of **lists** for tags
-and machines:
+The new `instances` format uses **attribute sets** instead of **lists** for tags and machines:
 
 ```nix
 # ❌ Old format (lists)
@@ -244,70 +239,73 @@ roles.moon.machines.eva = { };
 roles.moon.machines.eve = { };
 ```
 
-______________________________________________________________________
+---
 
 ## Migration Status of clanModules
 
 The following table shows the migration status of each deprecated clanModule:
 
-| clanModule | Migration Status | Notes |
+| clanModule               | Migration Status                                                  | Notes                                                            |
 |--------------------------|-------------------------------------------------------------------|------------------------------------------------------------------|
-| `admin` | ✅ [Migrated](../../reference/clanServices/admin.md) | | |
-`auto-upgrade` | ❌ Removed | | | `borgbackup-static` | ❌ Removed | | |
-`borgbackup` | ✅ [Migrated](../../reference/clanServices/borgbackup.md) | | |
-`data-mesher` | ✅ [Migrated](../../reference/clanServices/data-mesher.md) | | |
-`deltachat` | ❌ Removed | | | `disk-id` | ❌ Removed | | | `dyndns` |
-[Being Migrated](https://git.clan.lol/clan/clan-core/pulls/4390) | | |
-`ergochat` | ❌ Removed | | | `garage` | ✅
-[Migrated](../../reference/clanServices/garage.md) | | | `golem-provider` | ❌
-Removed | | | `heisenbridge` | ❌ Removed | | | `importer` | ✅
-[Migrated](../../reference/clanServices/importer.md) | | | `iwd` | ❌ Removed |
-Use [wifi service](../../reference/clanServices/wifi.md) instead | |
-`localbackup` | ✅ [Migrated](../../reference/clanServices/localbackup.md) | | |
-`localsend` | ❌ Removed | | | `machine-id` | ❌ Removed | Now an
-[option](../../reference/clan.core/settings.md) | | `matrix-synapse` | ✅
-[Migrated](../../reference/clanServices/matrix-synapse.md) | | | `moonlight` | ❌
-Removed | | | `mumble` | ❌ Removed | | | `mycelium` | ✅
-[Migrated](../../reference/clanServices/mycelium.md) | | | `nginx` | ❌ Removed |
-| | `packages` | ✅ [Migrated](../../reference/clanServices/packages.md) | | |
-`postgresql` | ❌ Removed | Now an
-[option](../../reference/clan.core/settings.md) | | `root-password` | ✅
-[Migrated](../../reference/clanServices/users.md) | See
-[migration guide](../../reference/clanServices/users.md#migration-from-root-password-module)
-| | `single-disk` | ❌ Removed | | | `sshd` | ✅
-[Migrated](../../reference/clanServices/sshd.md) | | | `state-version` | ✅
-[Migrated](../../reference/clanServices/state-version.md) | | | `static-hosts` |
-❌ Removed | | | `sunshine` | ❌ Removed | | | `syncthing-static-peers` | ❌
-Removed | | | `syncthing` | ✅
-[Migrated](../../reference/clanServices/syncthing.md) | | | `thelounge` | ❌
-Removed | | | `trusted-nix-caches` | ✅
-[Migrated](../../reference/clanServices/trusted-nix-caches.md) | | |
-`user-password` | ✅ [Migrated](../../reference/clanServices/users.md) | | |
-`vaultwarden` | ❌ Removed | | | `xfce` | ❌ Removed | | | `zerotier-static-peers`
-| ❌ Removed | | | `zerotier` | ✅
-[Migrated](../../reference/clanServices/zerotier.md) | | | `zt-tcp-relay` | ❌
-Removed | |
+| `admin`                  | ✅ [Migrated](../../reference/clanServices/admin.md)              |                                                                  |
+| `auto-upgrade`           | ❌ Removed                                                        |                                                                  |
+| `borgbackup-static`      | ❌ Removed                                                        |                                                                  |
+| `borgbackup`             | ✅ [Migrated](../../reference/clanServices/borgbackup.md)         |                                                                  |
+| `data-mesher`            | ✅ [Migrated](../../reference/clanServices/data-mesher.md)        |                                                                  |
+| `deltachat`              | ❌ Removed                                                        |                                                                  |
+| `disk-id`                | ❌ Removed                                                        |                                                                  |
+| `dyndns`                 | [Being Migrated](https://git.clan.lol/clan/clan-core/pulls/4390)  |                                                                  |
+| `ergochat`               | ❌ Removed                                                        |                                                                  |
+| `garage`                 | ✅ [Migrated](../../reference/clanServices/garage.md)             |                                                                  |
+| `golem-provider`         | ❌ Removed                                                        |                                                                  |
+| `heisenbridge`           | ❌ Removed                                                        |                                                                  |
+| `importer`               | ✅ [Migrated](../../reference/clanServices/importer.md)           |                                                                  |
+| `iwd`                    | ❌ Removed                                                        | Use [wifi service](../../reference/clanServices/wifi.md) instead |
+| `localbackup`            | ✅ [Migrated](../../reference/clanServices/localbackup.md)        |                                                                  |
+| `localsend`              | ❌ Removed                                                        |                                                                  |
+| `machine-id`             | ❌ Removed                                                        | Now an [option](../../reference/clan.core/settings.md)           |
+| `matrix-synapse`         | ✅ [Migrated](../../reference/clanServices/matrix-synapse.md)     |                                                                  |
+| `moonlight`              | ❌ Removed                                                        |                                                                  |
+| `mumble`                 | ❌ Removed                                                        |                                                                  |
+| `mycelium`               | ✅ [Migrated](../../reference/clanServices/mycelium.md)           |                                                                  |
+| `nginx`                  | ❌ Removed                                                        |                                                                  |
+| `packages`               | ✅ [Migrated](../../reference/clanServices/packages.md)           |                                                                  |
+| `postgresql`             | ❌ Removed                                                        | Now an [option](../../reference/clan.core/settings.md)           |
+| `root-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              |                                                                  |
+| `single-disk`            | ❌ Removed                                                        |                                                                  |
+| `sshd`                   | ✅ [Migrated](../../reference/clanServices/sshd.md)               |                                                                  |
+| `state-version`          | ✅ [Migrated](../../reference/clanServices/state-version.md)      |                                                                  |
+| `static-hosts`           | ❌ Removed                                                        |                                                                  |
+| `sunshine`               | ❌ Removed                                                        |                                                                  |
+| `syncthing-static-peers` | ❌ Removed                                                        |                                                                  |
+| `syncthing`              | ✅ [Migrated](../../reference/clanServices/syncthing.md)          |                                                                  |
+| `thelounge`              | ❌ Removed                                                        |                                                                  |
+| `trusted-nix-caches`     | ✅ [Migrated](../../reference/clanServices/trusted-nix-caches.md) |                                                                  |
+| `user-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              |                                                                  |
+| `vaultwarden`            | ❌ Removed                                                        |                                                                  |
+| `xfce`                   | ❌ Removed                                                        |                                                                  |
+| `zerotier-static-peers`  | ❌ Removed                                                        |                                                                  |
+| `zerotier`               | ✅ [Migrated](../../reference/clanServices/zerotier.md)           |                                                                  |
+| `zt-tcp-relay`           | ❌ Removed                                                        |                                                                  |
 
-______________________________________________________________________
+---
 
-!!! Warning * Old `clanModules` (`class = "nixos"`) are deprecated and will be
-removed in the near future. * `inventory.services` is no longer recommended; use
-`inventory.instances` instead. * Module authors should begin exporting service
-modules under the `clan.modules` attribute of their flake.
+!!! Warning
+    * Old `clanModules` (`class = "nixos"`) are deprecated and will be removed in the near future.
+    * `inventory.services` is no longer recommended; use `inventory.instances` instead.
+    * Module authors should begin exporting service modules under the `clan.modules` attribute of their flake.
 
 ## Troubleshooting Common Migration Errors
 
 ### Error: "not of type `attribute set of (submodule)`"
 
-This error occurs when using lists instead of attribute sets for tags or
-machines:
+This error occurs when using lists instead of attribute sets for tags or machines:
 
 ```
 error: A definition for option `flake.clan.inventory.instances.borgbackup-blob64.roles.client.tags' is not of type `attribute set of (submodule)'.
 ```
 
-**Solution**: Convert lists to attribute sets as shown in the "Important Type
-Changes" section above.
+**Solution**: Convert lists to attribute sets as shown in the "Important Type Changes" section above.
 
 ### Error: "unsupported attribute `module`"
 
@@ -317,8 +315,7 @@ This error indicates the module structure is incorrect:
 error: Module ':anon-4:anon-1' has an unsupported attribute `module'.
 ```
 
-**Solution**: Ensure the `module` attribute has exactly two fields: `name` and
-`input`.
+**Solution**: Ensure the `module` attribute has exactly two fields: `name` and `input`.
 
 ### Error: "attribute 'pkgs' missing"
 
@@ -328,30 +325,25 @@ This suggests the instance configuration is trying to use imports incorrectly:
 error: attribute 'pkgs' missing
 ```
 
-**Solution**: Use the `module = { name = "..."; input = "..."; }` format instead
-of `imports`.
+**Solution**: Use the `module = { name = "..."; input = "..."; }` format instead of `imports`.
 
 ### Removed Features
 
-The following features from the old `services` format are no longer supported in
-`instances`:
+The following features from the old `services` format are no longer supported in `instances`:
 
 - Top-level `config` attribute (use `roles.<role>.settings` instead)
 - Direct module imports (use the `module` declaration instead)
 
 ### extraModules Support
 
-The `extraModules` attribute is still supported in the new instances format! The
-key change is how modules are specified:
+The `extraModules` attribute is still supported in the new instances format! The key change is how modules are specified:
 
 **Old format (string paths relative to clan root):**
-
 ```nix
 roles.client.extraModules = [ "nixosModules/borgbackup.nix" ];
 ```
 
 **New format (NixOS modules):**
-
 ```nix
 # Direct module reference
 roles.client.extraModules = [ ../nixosModules/borgbackup.nix ];
@@ -367,14 +359,11 @@ roles.client.extraModules = [
 ];
 ```
 
-The `extraModules` now expects actual **NixOS modules** rather than string
-paths. This provides better type checking and more flexibility in how modules
-are specified.
+The `extraModules` now expects actual **NixOS modules** rather than string paths. This provides better type checking and more flexibility in how modules are specified.
 
 **Alternative: Using @clan/importer**
 
-For scenarios where you need to import modules with specific tag-based
-targeting, you can also use the dedicated `@clan/importer` service:
+For scenarios where you need to import modules with specific tag-based targeting, you can also use the dedicated `@clan/importer` service:
 
 ```nix
 instances = {
@@ -389,6 +378,6 @@ instances = {
 
 ## Further reference
 
-- [Inventory Concept](../../concepts/inventory.md)
-- [Authoring a 'clan.service' module](../../guides/services/community.md)
-- [ClanServices](../clanServices.md)
+* [Inventory Concept](../../concepts/inventory.md)
+* [Authoring a 'clan.service' module](../../guides/services/community.md)
+* [ClanServices](../clanServices.md)

docs/site/guides/migrations/migration-facts-vars.md

@@ -1,20 +1,16 @@
 # Migrate modules from `facts` to `vars`.
 
-For a high level overview about `vars` see our
-[blog post](https://clan.lol/blog/vars/).
+For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/).
 
-This guide will help you migrate your modules that still use our
-[`facts`](../../guides/secrets.md) backend to the
-[`vars`](../../concepts/generators.md) backend.
+This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend
+to the [`vars`](../../concepts/generators.md) backend.
 
-The `vars` [module](../../reference/clan.core/vars.md) and the clan
-[command](../../reference/cli/vars.md) work in tandem, they should ideally be
-kept in sync.
+The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
 
 ## Keep Existing Values
 
-In order to keep existing values and move them from `facts` to `vars` we will
-need to set the corresponding option in the vars module:
+In order to keep existing values and move them from `facts` to `vars`
+we will need to set the corresponding option in the vars module:
 
 ```
 migrateFact = "fact-name"
@@ -23,10 +19,10 @@ migrateFact = "fact-name"
 This will now check on `vars` generation if there is an existing `fact` with the
 name already present and if that is the case will migrate it to `vars`.
 
-Let us look at the mapping a little closer. Suppose we have the following fact:
-`facts.services.vaultwarden.secret.admin`. This would read as follows: The
-`vaultwarden` `fact` service has the `admin` secret. In order to migrate this
-fact we would need to have the following `vars` configuration:
+Let us look at the mapping a little closer.
+Suppose we have the following fact: `facts.services.vaultwarden.secret.admin`.
+This would read as follows: The `vaultwarden` `fact` service has the `admin` secret.
+In order to migrate this fact we would need to have the following `vars` configuration:
 
 ```nix
 vars.generators.vaultwarden = {
@@ -35,14 +31,13 @@ vars.generators.vaultwarden = {
 };
 ```
 
-And this would read as follows: The vaultwarden `vars` module generates the
-admin file.
+And this would read as follows: The vaultwarden `vars` module generates the admin file.
+
 
 ## Prompts
 
-Because prompts can be a necessity for certain systems `vars` have a shorthand
-for defining them. A prompt is a request for user input. Let us look how user
-input used to be handled in facts:
+Because prompts can be a necessity for certain systems `vars` have a shorthand for defining them.
+A prompt is a request for user input. Let us look how user input used to be handled in facts:
 
 ```nix
 facts.services.forgejo-api = {
@@ -51,9 +46,7 @@ facts.services.forgejo-api = {
     generator.script = "cp $prompt_value > $secret/token";
 };
 ```
-
 To have analogous functionality in `vars`:
-
 ```nix
 vars.generators.forgejo-api = {
     prompts.token = {
@@ -62,11 +55,8 @@ vars.generators.forgejo-api = {
     };
 };
 ```
-
-This does not only simplify prompting, it also now allows us to define multiple
-prompts in one generator. A more analogous way to the `fact` method is
-available, in case the module author needs more flexibility with the prompt
-input:
+This does not only simplify prompting, it also now allows us to define multiple prompts in one generator.
+A more analogous way to the `fact` method is available, in case the module author needs more flexibility with the prompt input:
 
 ```nix
 vars.generators.forgejo-api = {
@@ -102,9 +92,8 @@ facts.services.syncthing = {
 };
 ```
 
-This would be the corresponding `vars` module, which also will migrate existing
-facts.
 
+This would be the corresponding `vars` module, which also will migrate existing facts.
 ```nix
 vars.generators.syncthing = {
   migrateFact = "syncthing";
@@ -127,15 +116,12 @@ vars.generators.syncthing = {
   '';
 };
 ```
+Most of the usage patterns stay the same, but `vars` have a more ergonomic interface.
+There are not two different ways to define files anymore (public/secret).
+Now files are defined under the `files` attribute and are secret by default.
 
-Most of the usage patterns stay the same, but `vars` have a more ergonomic
-interface. There are not two different ways to define files anymore
-(public/secret). Now files are defined under the `files` attribute and are
-secret by default.
 
 ## Happy Migration
 
-We hope this gives you a clear path to start and finish your migration from
-`facts` to `vars`. Please do not hesitate reaching out if something is still
-unclear - either through [matrix](https://matrix.to/#/#clan:clan.lol) or through
-our git [forge](https://git.clan.lol/clan/clan-core).
+We hope this gives you a clear path to start and finish your migration from `facts` to `vars`.
+Please do not hesitate reaching out if something is still unclear - either through [matrix](https://matrix.to/#/#clan:clan.lol) or through our git [forge](https://git.clan.lol/clan/clan-core).

docs/site/guides/migrations/migration-guide.md

@@ -1,27 +1,23 @@
-# Convert existing NixOS configurations
+# Migrate existing NixOS configurations
 
-This guide will help you convert your existing NixOS configurations into a Clan.
+This guide will help you migrate your existing NixOS configurations into Clan.
 
-!!! Warning Migrating instead of starting new can be trickier and might lead to
-bugs or unexpected issues. We recommend reading the
-[Getting Started](./index.md) guide first.
-
-```
-Once you have a working setup and understand the concepts transfering your NixOS configurations over is easy.
-```
-
-## Back up your existing configuration
+!!! Warning
+    Migrating instead of starting new can be trickier and might lead to bugs or
+    unexpected issues. We recommend following the [Getting Started](../getting-started/index.md) guide first. Once you have a working setup, you can easily transfer your NixOS configurations over.
 
+## Back up your existing configuration!
 Before you start, it is strongly recommended to back up your existing
-configuration in any form you see fit. If you use version control to manage your
-configuration changes, it is also a good idea to follow the migration guide in a
-separte branch until everything works as expected.
+configuration in any form you see fit. If you use version control to manage
+your configuration changes, it is also a good idea to follow the migration
+guide in a separte branch until everything works as expected.
+
 
 ## Starting Point
 
 We assume you are already using NixOS flakes to manage your configuration. If
-not, migrate to a flake-based setup following the official
-[NixOS documentation](https://nix.dev/manual/nix/2.25/command-ref/new-cli/nix3-flake.html).
+not, migrate to a flake-based setup following the official [NixOS
+documentation](https://nix.dev/manual/nix/2.25/command-ref/new-cli/nix3-flake.html).
 The snippet below shows a common Nix flake. For this example we will assume you
 have have two hosts: **berlin** and **cologne**.
 
@@ -47,9 +43,10 @@ have have two hosts: **berlin** and **cologne**.
 }
 ```
 
-## 1. Add `clan-core` to `inputs`
+## Add clan-core Input
 
-Add `clan-core` to your flake as input.
+Add `clan-core` to your flake as input. It will provide everything we need to
+manage your configurations with clan.
 
 ```nix
 inputs.clan-core = {
@@ -59,7 +56,7 @@ inputs.clan-core = {
 }
 ```
 
-## 2. Update Outputs
+## Update Outputs
 
 To be able to access our newly added dependency, it has to be added to the
 output parameters.
@@ -69,9 +66,9 @@ output parameters.
 +  outputs = { self, nixpkgs, clan-core }:
 ```
 
-The existing `nixosConfigurations` output of your flake will be created by clan.
-In addition, a new `clanInternals` output will be added. Since both of these are
-provided by the output of `clan-core.lib.clan`, a common syntax is to use a
+The existing `nixosConfigurations` output of your flake will be created by
+clan. In addition, a new `clanInternals` output will be added. Since both of
+these are provided by the output of `clan-core.lib.clan`, a common syntax is to use a
 `let...in` statement to create your clan and access it's parameters in the flake
 outputs.
 
@@ -106,22 +103,26 @@ For the provide flake example, your flake should now look like this:
     };
   in
   {
-      inherit (clan.config) nixosConfigurations nixosModules clanInternals;
-      clan = clan.config;
+      nixosConfigurations = clan.nixosConfigurations;
+
+      inherit (clan) clanInternals;
+
+      clan = {
+        inherit (clan) templates;
+      };
   };
 }
 ```
 
-✅ Et voilà! Your existing hosts are now part of a clan.
-
-Existing Nix tooling should still work as normal. To check that you didn't make
-any errors, run `nix flake show` and verify both hosts are still recognized as
-if nothing had changed. You should also see the new `clan` output.
+Et voilà! Your existing hosts are now part of a clan. Existing Nix tooling
+should still work as normal. To check that you didn't make any errors, run `nix
+flake show` and verify both hosts are still recognized as if nothing had
+changed. You should also see the new `clanInternals` output.
 
 ```
 ❯ nix flake show
 git+file:///my-nixos-config
-├───clan: unknown
+├───clanInternals: unknown
 └───nixosConfigurations
     ├───berlin: NixOS configuration
     └───cologne: NixOS configuration
@@ -130,7 +131,7 @@ git+file:///my-nixos-config
 Of course you can also rebuild your configuration using `nixos-rebuild` and
 veryify everything still works.
 
-## 3. Add `clan-cli` to your `devShells`
+## Add Clan CLI devShell
 
 At this point Clan is set up, but you can't use the CLI yet. To do so, it is
 recommended to expose it via a `devShell` in your flake. It is also possible to
@@ -162,8 +163,8 @@ cologne
 
 ## Specify Targets
 
-Clan needs to know where it can reach your hosts. For testing purpose set
-`clan.core.networking.targetHost` to the machines adress or hostname.
+Clan needs to know where it can reach your hosts. For each of your hosts, set
+`clan.core.networking.targetHost` to its adress or hostname.
 
 ```nix
 # machines/berlin/configuration.nix
@@ -172,9 +173,6 @@ Clan needs to know where it can reach your hosts. For testing purpose set
 }
 ```
 
-See our guide on for properly
-[configuring machines networking](../networking.md)
-
 ## Next Steps
 
 You are now fully set up. Use the CLI to manage your hosts or proceed to

docs/site/guides/networking.md

@@ -1,197 +0,0 @@
-# Connecting to Your Machines
-
-Clan provides automatic networking with fallback mechanisms to reliably connect
-to your machines.
-
-## Option 1: Automatic Networking with Fallback (Recommended)
-
-Clan's networking module automatically manages connections through various
-network technologies with intelligent fallback. When you run `clan ssh` or
-`clan machines update`, Clan tries each configured network by priority until one
-succeeds.
-
-### Basic Setup with Internet Service
-
-For machines with public IPs or DNS names, use the `internet` service to
-configure direct SSH while keeping fallback options:
-
-```{.nix title="flake.nix" hl_lines="7-10 14-16"}
-{
-  outputs = { self, clan-core, ... }:
-    let
-      clan = clan-core.lib.clan {
-        inventory.instances = {
-          # Direct SSH with fallback support
-          internet = {
-            roles.default.machines.server1 = {
-              settings.address = "server1.example.com";
-            };
-            roles.default.machines.server2 = {
-              settings.address = "192.168.1.100";
-            };
-          };
-
-          # Fallback: Secure connections via Tor
-          tor = {
-            roles.server.tags.nixos = { };
-          };
-        };
-      };
-    in
-    {
-      inherit (clan.config) nixosConfigurations;
-    };
-}
-```
-
-### Advanced Setup with Multiple Networks
-
-```{.nix title="flake.nix" hl_lines="7-10 13-16 19-21"}
-{
-  outputs = { self, clan-core, ... }:
-    let
-      clan = clan-core.lib.clan {
-        inventory.instances = {
-          # Priority 1: Try direct connection first
-          internet = {
-            roles.default.machines.publicserver = {
-              settings.address = "public.example.com";
-            };
-          };
-
-          # Priority 2: VPN for internal machines
-          zerotier = {
-            roles.controller.machines."controller" = { };
-            roles.peer.tags.nixos = { };
-          };
-
-          # Priority 3: Tor as universal fallback
-          tor = {
-            roles.server.tags.nixos = { };
-          };
-        };
-      };
-    in
-    {
-      inherit (clan.config) nixosConfigurations;
-    };
-}
-```
-
-### How It Works
-
-Clan automatically tries networks in order of priority:
-
-1. Direct internet connections (if configured)
-2. VPN networks (ZeroTier, Tailscale, etc.)
-3. Tor hidden services
-4. Any other configured networks
-
-If one network fails, Clan automatically tries the next.
-
-### Useful Commands
-
-```bash
-# View all configured networks and their status
-clan network list
-
-# Test connectivity through all networks
-clan network ping machine1
-
-# Show complete network topology
-clan network overview
-```
-
-## Option 2: Manual targetHost (Bypasses Fallback!)
-
-!!! warning Setting `targetHost` directly **disables all automatic networking
-and fallback**. Only use this if you need complete control and don't want Clan's
-intelligent connection management.
-
-### Using Inventory (For Static Addresses)
-
-Use inventory-level `targetHost` when the address is **static** and doesn't
-depend on NixOS configuration:
-
-```{.nix title="flake.nix" hl_lines="8"}
-{
-  outputs = { self, clan-core, ... }:
-    let
-      clan = clan-core.lib.clan {
-        inventory.machines.server = {
-          # WARNING: This bypasses all networking modules!
-          # Use for: Static IPs, DNS names, known hostnames
-          deploy.targetHost = "root@192.168.1.100";
-        };
-      };
-    in
-    {
-      inherit (clan.config) nixosConfigurations;
-    };
-}
-```
-
-**When to use inventory-level:**
-
-- Static IP addresses: `"root@192.168.1.100"`
-- DNS names: `"user@server.example.com"`
-- Any address that doesn't change based on machine configuration
-
-### Using NixOS Configuration (For Dynamic Addresses)
-
-Use machine-level `targetHost` when you need to **interpolate values from the
-NixOS configuration**:
-
-```{.nix title="flake.nix" hl_lines="7"}
-{
-  outputs = { self, clan-core, ... }:
-    let
-      clan = clan-core.lib.clan {
-        machines.server = { config, ... }: {
-          # WARNING: This also bypasses all networking modules!
-          # REQUIRED for: Addresses that depend on NixOS config
-          clan.core.networking.targetHost = "root@${config.networking.hostName}.local";
-        };
-      };
-    in
-    {
-      inherit (clan.config) nixosConfigurations;
-    };
-}
-```
-
-**When to use machine-level (NixOS config):**
-
-- Using hostName from config: `"root@${config.networking.hostName}.local"`
-- Building from multiple config values:
-  `"${config.users.users.deploy.name}@${config.networking.hostName}"`
-- Any address that depends on evaluated NixOS configuration
-
-!!! info "Key Difference" **Inventory-level** (`deploy.targetHost`) is evaluated
-immediately and works with static strings. **Machine-level**
-(`clan.core.networking.targetHost`) is evaluated after NixOS configuration and
-can access `config.*` values.
-
-## Quick Decision Guide
-
-| Scenario | Recommended Approach | Why |
-|----------|---------------------|-----| | Public servers | `internet` service |
-Keeps fallback options | | Mixed infrastructure | Multiple networks | Automatic
-failover | | Machines behind NAT | ZeroTier/Tor | NAT traversal with fallback |
-| Testing/debugging | Manual targetHost | Full control, no magic | | Single
-static machine | Manual targetHost | Simple, no overhead |
-
-## Command-Line Override
-
-The `--target-host` flag bypasses ALL networking configuration:
-
-```bash
-# Emergency access - ignores all networking config
-clan machines update server --target-host root@backup-ip.com
-
-# Direct SSH - no fallback attempted
-clan ssh laptop --target-host user@10.0.0.5
-```
-
-Use this for debugging or emergency access when automatic networking isn't
-working.

docs/site/guides/secrets.md

@@ -1,29 +1,24 @@
-This article provides an overview over the underlying secrets system which is
-used by [Vars](../concepts/generators.md). Under most circumstances you should
-use [Vars](../concepts/generators.md) directly instead.
+This article provides an overview over the underlying secrets system which is used by [Vars](../concepts/generators.md).
+Under most circumstances you should use [Vars](../concepts/generators.md) directly instead.
 
-Consider using `clan secrets` only for managing admin users and groups, as well
-as a debugging tool.
+Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool.
 
-Manually interacting with secrets via `clan secrets [set|remove]`, etc may break
-the integrity of your `Vars` state.
+Manually interacting with secrets via `clan secrets [set|remove]`, etc may break the integrity of your `Vars` state.
 
-______________________________________________________________________
+---
 
-Clan enables encryption of secrets (such as passwords & keys) ensuring security
-and ease-of-use among users.
+Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
 
-By default, Clan uses the [sops](https://github.com/getsops/sops) format and
-integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
-Clan can also be configured to be used with other secret store
-[backends](../reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
+By default, Clan uses the [sops](https://github.com/getsops/sops) format
+and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
+Clan can also be configured to be used with other secret store [backends](../reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
 
 ## Create Your Admin Keypair
 
 To get started, you'll need to create **your admin keypair**.
 
-!!! info Don't worry — if you've already made one before, this step won't change
-or overwrite it.
+!!! info
+    Don't worry — if you've already made one before, this step won't change or overwrite it.
 
 ```bash
 clan secrets key generate
@@ -38,23 +33,22 @@ Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your us
 Also add your age public key to the repository with 'clan secrets users add YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username)
 ```
 
-!!! warning Make sure to keep a safe backup of the private key you've just
-created. If it's lost, you won't be able to get to your secrets anymore because
-they all need the admin key to be unlocked.
+!!! warning
+    Make sure to keep a safe backup of the private key you've just created.
+    If it's lost, you won't be able to get to your secrets anymore because they all need the admin key to be unlocked.
 
-If you already have an [age] secret key and want to use that instead, you can
-simply edit `~/.config/sops/age/keys.txt`:
+If you already have an [age] secret key and want to use that instead, you can simply edit `~/.config/sops/age/keys.txt`:
 
 ```title="~/.config/sops/age/keys.txt"
 AGE-SECRET-KEY-13GWMK0KNNKXPTJ8KQ9LPSQZU7G3KU8LZDW474NX3D956GGVFAZRQTAE3F4
 ```
 
-Alternatively, you can provide your [age] secret key as an environment variable
-`SOPS_AGE_KEY`, or in a different file using `SOPS_AGE_KEY_FILE`. For more
-information see the [SOPS] guide on [encrypting with age].
+Alternatively, you can provide your [age] secret key as an environment variable `SOPS_AGE_KEY`, or in a different file
+using `SOPS_AGE_KEY_FILE`.
+For more information see the [SOPS] guide on [encrypting with age].
 
-!!! note It's safe to add any secrets created by the clan CLI and placed in your
-repository to version control systems like `git`.
+!!! note
+    It's safe to add any secrets created by the clan CLI and placed in your repository to version control systems like `git`.
 
 ## Add Your Public Key(s)
 
@@ -62,8 +56,7 @@ repository to version control systems like `git`.
 clan secrets users add $USER --age-key <your_public_key>
 ```
 
-It's best to choose the same username as on your Setup/Admin Machine that you
-use to control the deployment with.
+It's best to choose the same username as on your Setup/Admin Machine that you use to control the deployment with.
 
 Once run this will create the following files:
 
@@ -73,21 +66,17 @@ sops/
     └── <your_username>/
         └── key.json
 ```
+If you followed the quickstart tutorial all necessary secrets are initialized at this point.
 
-If you followed the quickstart tutorial all necessary secrets are initialized at
-this point.
+!!! note
+    You can add multiple age keys for a user by providing multiple `--age-key <your_public_key>` flags:
 
-!!! note You can add multiple age keys for a user by providing multiple
-`--age-key <your_public_key>` flags:
-
-````
-```console
-clan secrets users add $USER \
-    --age-key <your_public_key_1> \
-    --age-key <your_public_key_2> \
-    ...
-```
-````
+    ```console
+    clan secrets users add $USER \
+        --age-key <your_public_key_1> \
+        --age-key <your_public_key_2> \
+        ...
+    ```
 
 ## Manage Your Public Key(s)
 
@@ -122,6 +111,11 @@ To remove a key from your user:
 clan secrets users remove-key $USER --age-key <your_public_key>
 ```
 
+[age]: https://github.com/FiloSottile/age
+[age plugin]: https://github.com/FiloSottile/awesome-age?tab=readme-ov-file#plugins
+[sops]: https://github.com/getsops/sops
+[encrypting with age]: https://github.com/getsops/sops?tab=readme-ov-file#encrypting-using-age
+
 ## Adding a Secret
 
 ```shellSession
@@ -145,10 +139,8 @@ clan secrets list
 
 A NixOS machine will automatically import all secrets that are encrypted for the
 current machine. At runtime it will use the host key to decrypt all secrets into
-an in-memory, non-persistent filesystem using
-[sops-nix](https://github.com/Mic92/sops-nix). In your nixos configuration you
-can get a path to secrets like this `config.sops.secrets.<name>.path`. For
-example:
+an in-memory, non-persistent filesystem using [sops-nix](https://github.com/Mic92/sops-nix).
+In your nixos configuration you can get a path to secrets like this `config.sops.secrets.<name>.path`. For example:
 
 ```nix
 { config, ...}: {
@@ -163,8 +155,7 @@ example:
 
 ## Assigning Access
 
-When using `clan secrets set <secret>` without arguments, secrets are encrypted
-for the key of the user named like your current $USER.
+When using `clan secrets set <secret>` without arguments, secrets are encrypted for the key of the user named like your current $USER.
 
 To add machines/users to an existing secret use:
 
@@ -212,8 +203,7 @@ Here's how to get started:
    clan secrets groups add-secret <group_name> <secret_name>
    ```
 
-**TIP** To encrypt all secrets of a machine for a specific group, use the
-following NixOS configuration:
+**TIP** To encrypt all secrets of a machine for a specific group, use the following NixOS configuration:
 
 ```
 {
@@ -223,8 +213,7 @@ following NixOS configuration:
 
 ### Adding Machine Keys
 
-New machines in Clan come with age keys stored in
-`./sops/machines/<machine_name>`. To list these machines:
+New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
 
 ```bash
  clan secrets machines list
@@ -244,29 +233,24 @@ To fetch an age key from an SSH host key:
 
 ### Migration: Importing existing sops-based keys / sops-nix
 
-`clan secrets` stores each secret in a single file, whereas
-[sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in
-a yaml or json document.
+`clan secrets` stores each secret in a single file, whereas [sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in a yaml or json document.
 
-If you already happened to use sops-nix, you can migrate by using the
-`clan secrets import-sops` command by importing these files:
+If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these files:
 
 ```bash
 % clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml
 ```
 
-This will create secrets for each secret found in
-`nixos/matchbox/secrets/secrets.yaml` in a `./sops` folder of your repository.
-Each member of the group `admins` in this case will be able to decrypt the
-secrets with their respective key.
+This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a `./sops` folder of your repository.
+Each member of the group `admins` in this case will be able to decrypt the secrets with their respective key.
+
+Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine,
+you can now remove `sops.secrets.<secrets> = { };` unless you need to specify more options for the secret like owner/group of the secret file.
 
-Since our clan secret module will auto-import secrets that are encrypted for a
-particular nixos machine, you can now remove `sops.secrets.<secrets> = { };`
-unless you need to specify more options for the secret like owner/group of the
-secret file.
 
 ## Indepth Explanation
 
+
 The secrets system conceptually knows two different entities:
 
 - **Machine**: consumes secrets
@@ -274,50 +258,33 @@ The secrets system conceptually knows two different entities:
 
 **A Users** Can add or revoke machines' access to secrets.
 
-**A machine** Can decrypt secrets that where encrypted specifically for that
-machine.
+**A machine** Can decrypt secrets that where encrypted specifically for that machine.
 
-!!! Danger **Always make sure at least one _User_ has access to a secret**.
-Otherwise you could lock yourself out from accessing the secret.
+!!! Danger
+    **Always make sure at least one _User_ has access to a secret**. Otherwise you could lock yourself out from accessing the secret.
 
 ### Inherited implications
 
-By default clan uses [sops](https://github.com/getsops/sops) through
-[sops-nix](https://github.com/Mic92/sops-nix) for managing its secrets which
-inherits some implications that are important to understand:
-
-- **Public/Private keys**: Entities are identified via their public keys. Each
-  Entity can use their respective private key to decrypt a secret.
+By default clan uses [sops](https://github.com/getsops/sops) through [sops-nix](https://github.com/Mic92/sops-nix) for managing its secrets which inherits some implications that are important to understand:
 
+- **Public/Private keys**: Entities are identified via their public keys. Each Entity can use their respective private key to decrypt a secret.
 - **Public keys are stored**: All Public keys are stored inside the repository
+- **Secrets are stored Encrypted**: secrets are stored inside the repository encrypted with the respective public keys
+- **Secrets are deployed encrypted**: Fully encrypted secrets are deployed to machines at deployment time.
+- **Secrets are decrypted by sops on-demand**: Each machine decrypts its secrets at runtime and stores them at an ephemeral location.
+- **Machine key-pairs are auto-generated**: When a machine is created **no user-interaction is required** to setup public/private key-pairs.
+- **secrets are re-encrypted**: In case machines, users or groups are modified secrets get re-encrypted on demand.
 
-- **Secrets are stored Encrypted**: secrets are stored inside the repository
-  encrypted with the respective public keys
+    !!! Important
+        After revoking access to a secret you should also change the underlying secret. i.e. change the API key, or the password.
 
-- **Secrets are deployed encrypted**: Fully encrypted secrets are deployed to
-  machines at deployment time.
-
-- **Secrets are decrypted by sops on-demand**: Each machine decrypts its secrets
-  at runtime and stores them at an ephemeral location.
-
-- **Machine key-pairs are auto-generated**: When a machine is created **no
-  user-interaction is required** to setup public/private key-pairs.
-
-- **secrets are re-encrypted**: In case machines, users or groups are modified
-  secrets get re-encrypted on demand.
-
-  !!! Important After revoking access to a secret you should also change the
-  underlying secret. i.e. change the API key, or the password.
-
-______________________________________________________________________
+---
 
 ### Machine and user keys
 
-The following diagrams illustrates how a user can provide a secret (i.e. a
-Password).
+The following diagrams illustrates how a user can provide a secret (i.e. a Password).
 
-- By using the **Clan CLI** a user encrypts the password with both the **User
-  public-key** and the **machine's public-key**
+- By using the **Clan CLI** a user encrypts the password with both the **User public-key** and the **machine's public-key**
 
 - The *Machine* can decrypt the password with its private-key on demand.
 
@@ -338,14 +305,14 @@ Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
 @enduml
 ```
 
+
 #### User groups
 
 Here we illustrate how machine groups work.
 
 Common use cases:
 
-- **Shared Management**: Access among multiple users. I.e. a subset of
-  secrets/machines that have two admins
+- **Shared Management**: Access among multiple users. I.e. a subset of secrets/machines that have two admins
 
 ```plantuml
 @startuml
@@ -368,7 +335,7 @@ Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
 
 <!-- TODO: See also [Groups Reference](#groups-reference) -->
 
-______________________________________________________________________
+---
 
 #### Machine groups
 
@@ -399,9 +366,10 @@ Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their priv
 
 <!-- TODO: See also [Groups Reference](#groups-reference) -->
 
+
+
 See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more
 examples.
 
-[age]: https://github.com/FiloSottile/age
-[encrypting with age]: https://github.com/getsops/sops?tab=readme-ov-file#encrypting-using-age
-[sops]: https://github.com/getsops/sops
+
+

docs/site/guides/secure-boot.md

@@ -1,8 +1,4 @@
-At the moment, NixOS/Clan does not support
-[Secure Boot](https://wiki.gentoo.org/wiki/Secure_Boot). Therefore, you need to
-disable it in the BIOS. You can watch this
-[video guide](https://www.youtube.com/watch?v=BKVShiMUePc) or follow the
-instructions below:
+At the moment, NixOS/Clan does not support [Secure Boot](https://wiki.gentoo.org/wiki/Secure_Boot). Therefore, you need to disable it in the BIOS. You can watch this [video guide](https://www.youtube.com/watch?v=BKVShiMUePc) or follow the instructions below:
 
 ## Insert the USB Stick
 
@@ -11,46 +7,49 @@ instructions below:
 ## Access the UEFI/BIOS Menu
 
 - Restart your computer.
+- As your computer restarts, press the appropriate key to enter the UEFI/BIOS settings.
+??? tip "The key depends on your laptop or motherboard manufacturer. Click to see a reference list:"
 
-- As your computer restarts, press the appropriate key to enter the UEFI/BIOS
-  settings. ??? tip "The key depends on your laptop or motherboard manufacturer.
-  Click to see a reference list:"
+    | Manufacturer       | UEFI/BIOS Key(s)          |
+    |--------------------|---------------------------|
+    | ASUS               | `Del`, `F2`               |
+    | MSI                | `Del`, `F2`               |
+    | Gigabyte           | `Del`, `F2`               |
+    | ASRock             | `Del`, `F2`               |
+    | Lenovo             | `F1`, `F2`, `Enter` (alternatively `Fn + F2`) |
+    | HP                 | `Esc`, `F10`              |
+    | Dell               | `F2`, `Fn + F2`, `Esc`    |
+    | Acer               | `F2`, `Del`               |
+    | Samsung            | `F2`, `F10`               |
+    | Toshiba            | `F2`, `Esc`               |
+    | Sony               | `F2`, `Assist` button     |
+    | Fujitsu            | `F2`                      |
+    | Microsoft Surface  | `Volume Up` + `Power`     |
+    | IBM/Lenovo ThinkPad| `Enter`, `F1`, `F12`      |
+    | Biostar            | `Del`                     |
+    | Zotac              | `Del`, `F2`               |
+    | EVGA               | `Del`                     |
+    | Origin PC          | `F2`, `Delete`            |
 
-  | Manufacturer | UEFI/BIOS Key(s) |
-  |--------------------|---------------------------| | ASUS | `Del`, `F2` | |
-  MSI | `Del`, `F2` | | Gigabyte | `Del`, `F2` | | ASRock | `Del`, `F2` | |
-  Lenovo | `F1`, `F2`, `Enter` (alternatively `Fn + F2`) | | HP | `Esc`, `F10` |
-  | Dell | `F2`, `Fn + F2`, `Esc` | | Acer | `F2`, `Del` | | Samsung | `F2`,
-  `F10` | | Toshiba | `F2`, `Esc` | | Sony | `F2`, `Assist` button | | Fujitsu |
-  `F2` | | Microsoft Surface | `Volume Up` + `Power` | | IBM/Lenovo ThinkPad|
-  `Enter`, `F1`, `F12` | | Biostar | `Del` | | Zotac | `Del`, `F2` | | EVGA |
-  `Del` | | Origin PC | `F2`, `Delete` |
-
-  !!! Note Pressing the key quickly and repeatedly is sometimes necessary to
-  access the UEFI/BIOS menu, as the window to enter this mode is brief.
+    !!! Note
+        Pressing the key quickly and repeatedly is sometimes necessary to access the UEFI/BIOS menu, as the window to enter this mode is brief.
 
 ## Access Advanced Mode (Optional)
 
-- If your UEFI/BIOS has a `Simple` or `Easy` mode interface, look for an option
-  labeled `Advanced Mode` (often found in the lower right corner).
-- Click on `Advanced Mode` to access more settings. This step is optional, as
-  your boot settings might be available in the basic view.
+- If your UEFI/BIOS has a `Simple` or `Easy` mode interface, look for an option labeled `Advanced Mode` (often found in the lower right corner).
+- Click on `Advanced Mode` to access more settings. This step is optional, as your boot settings might be available in the basic view.
 
 ## Disable Secure Boot
 
-- Locate the `Secure Boot` option in your UEFI/BIOS settings. This is typically
-  found under a `Security` tab, `Boot` tab, or a similarly named section.
+- Locate the `Secure Boot` option in your UEFI/BIOS settings. This is typically found under a `Security` tab, `Boot` tab, or a similarly named section.
 - Set the `Secure Boot` option to `Disabled`.
 
 ## Change Boot Order
 
-- Find the option to adjust the boot order—often labeled `Boot Order`,
-  `Boot Sequence`, or `Boot Priority`.
-- Ensure that your USB device is set as the first boot option. This allows your
-  computer to boot from the USB stick.
+- Find the option to adjust the boot order—often labeled `Boot Order`, `Boot Sequence`, or `Boot Priority`.
+- Ensure that your USB device is set as the first boot option. This allows your computer to boot from the USB stick.
 
 ## Save and Exit
 
-- Save your changes before exiting the UEFI/BIOS menu. Look for a `Save & Exit`
-  option or press the corresponding function key (often `F10`).
+- Save your changes before exiting the UEFI/BIOS menu. Look for a `Save & Exit` option or press the corresponding function key (often `F10`).
 - Your computer should now restart and boot from the USB stick.

docs/site/guides/services/community.md

@@ -2,24 +2,18 @@
 
 ## Service Module Specification
 
-This section explains how to author a clan service module. We discussed the
-initial architecture in
-[01-clan-service-modules](../../decisions/01-ClanModules.md) and decided to
-rework the format.
+This section explains how to author a clan service module.
+We discussed the initial architecture in [01-clan-service-modules](../../decisions/01-ClanModules.md) and decided to rework the format.
 
-For the full specification and current state see:
-**[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)**
+For the full specification and current state see: **[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)**
 
 ### A Minimal module
 
-First of all we need to register our module into the `clan.modules` attribute.
-Make sure to choose a unique name so the module doesn't have a name collision
-with any of the core modules.
+First of all we need to register our module into the `clan.modules` attribute. Make sure to choose a unique name so the module doesn't have a name collision with any of the core modules.
 
 While not required we recommend to prefix your module attribute name.
 
-If you export the module from your flake, other people will be able to import it
-and use it within their clan.
+If you export the module from your flake, other people will be able to import it and use it within their clan.
 
 i.e. `@hsjobeki/customNetworking`
 
@@ -41,9 +35,8 @@ outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } ({
 
 The imported module file must fulfill at least the following requirements:
 
-- Be an actual module. That means: Be either an attribute set; or a function
-  that returns an attribute set.
-- Required \`\_class = "clan.service"
+- Be an actual module. That means: Be either an attribute set; or a function that returns an attribute set.
+- Required `_class = "clan.service"
 - Required `manifest.name = "<name of the provided service>"`
 
 ```nix title="/service-modules/networking.nix"
@@ -54,28 +47,19 @@ The imported module file must fulfill at least the following requirements:
 }
 ```
 
-For more attributes see:
-**[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)**
+For more attributes see: **[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)**
 
 ### Adding functionality to the module
 
-While the very minimal module is valid in itself it has no way of adding any
-machines to it, because it doesn't specify any roles.
+While the very minimal module is valid in itself it has no way of adding any machines to it, because it doesn't specify any roles.
 
-The next logical step is to think about the interactions between the machines
-and define *roles* for them.
+The next logical step is to think about the interactions between the machines and define *roles* for them.
 
 Here is a short guide with some conventions:
 
-- [ ] If they all have the same relation to each other `peer` is commonly used.
-  `peers` can often talk to each other directly.
-- [ ] Often machines don't necessarily have direct relation to each other and
-  there is one elevated machine in the middle classically know as
-  `client-server`. `clients` are less likely to talk directly to each other than
-  `peers`
-- [ ] If your machines don't have any relation and/or interactions to each other
-  you should reconsider if the desired functionality is really a multi-host
-  service.
+- [ ] If they all have the same relation to each other `peer` is commonly used. `peers` can often talk to each other directly.
+- [ ] Often machines don't necessarily have direct relation to each other and there is one elevated machine in the middle classically know as `client-server`. `clients` are less likely to talk directly to each other than `peers`
+- [ ] If your machines don't have any relation and/or interactions to each other you should reconsider if the desired functionality is really a multi-host service.
 
 ```nix title="/service-modules/networking.nix"
 {
@@ -161,16 +145,14 @@ Next we need to define the settings and the behavior of these distinct roles.
 
 ## Using values from a NixOS machine inside the module
 
-!!! Example "Experimental Status" This feature is experimental and should be
-used with care.
+!!! Example "Experimental Status"
+    This feature is experimental and should be used with care.
 
 Sometimes a settings value depends on something within a machines `config`.
 
-Since the `interface` is defined completely machine-agnostic this means values
-from a machine cannot be set in the traditional way.
+Since the `interface` is defined completely machine-agnostic this means values from a machine cannot be set in the traditional way.
 
-The following example shows how to create a local instance of machine specific
-settings.
+The following example shows how to create a local instance of machine specific settings.
 
 ```nix title="someservice.nix"
 {
@@ -192,14 +174,11 @@ settings.
 }
 ```
 
-!!! Danger `localSettings` are a local attribute. Other machines cannot access
-it. If calling extendSettings is done that doesn't change the original
-`settings` this means if a different machine tries to access i.e
-`roles.client.settings` it would *NOT* contain your changes.
+!!! Danger
+    `localSettings` are a local attribute. Other machines cannot access it.
+    If calling extendSettings is done that doesn't change the original `settings` this means if a different machine tries to access i.e `roles.client.settings` it would *NOT* contain your changes.
 
-```
-Exposing the changed settings to other machines would come with a huge performance penalty, thats why we don't want to offer it.
-```
+    Exposing the changed settings to other machines would come with a huge performance penalty, thats why we don't want to offer it.
 
 ## Passing `self` or `pkgs` to the module
 
@@ -210,14 +189,11 @@ In general we found the following two best practices:
 1. Using `lib.importApply`
 2. Using a wrapper module
 
-Both have pros and cons. After all using `importApply` is the easier one, but
-might be more limiting sometimes.
+Both have pros and cons. After all using `importApply` is the easier one, but might be more limiting sometimes.
 
 ### Using `importApply`
 
-Using [importApply](https://github.com/NixOS/nixpkgs/pull/230588) is essentially
-the same as `import file` followed by a function-application; but preserves the
-error location.
+Using [importApply](https://github.com/NixOS/nixpkgs/pull/230588) is essentially the same as `import file` followed by a function-application; but preserves the error location.
 
 Imagine your module looks like this
 
@@ -258,8 +234,7 @@ outputs = inputs: flake-parts.lib.mkFlake { inherit inputs; } ({self, lib, ...}:
 }
 ```
 
-Then wrap the module and forward the variable `self` from the outer context into
-the module
+Then wrap the module and forward the variable `self` from the outer context into the module
 
 ```nix title="flake.nix"
 # ...
@@ -280,10 +255,9 @@ outputs = inputs: flake-parts.lib.mkFlake { inherit inputs; } ({self, lib, ...}:
 })
 ```
 
-The benefit of this approach is that downstream users can override the value of
-`myClan` by using `mkForce` or other priority modifiers.
+The benefit of this approach is that downstream users can override the value of `myClan` by using `mkForce` or other priority modifiers.
 
-______________________________________________________________________
+---
 
 ## Further
 

docs/site/guides/target-host.md

@@ -0,0 +1,84 @@
+# How to Set `targetHost` for a Machine
+
+The `targetHost` defines where the machine can be reached for operations like SSH or deployment. You can set it in two ways, depending on your use case.
+
+---
+
+## ✅ Option 1: Use the Inventory (Recommended for Static Hosts)
+
+If the hostname is **static**, like `server.example.com`, set it in the **inventory**:
+
+```{.nix title="flake.nix" hl_lines="8"}
+{
+  # edlided
+  outputs =
+    { self, clan-core, ... }:
+    let
+      # Sometimes this attribute set is defined in clan.nix
+      clan = clan-core.lib.clan {
+        inventory.machines.jon = {
+            deploy.targetHost = "root@server.example.com";
+        };
+      };
+    in
+    {
+      inherit (clan.config) nixosConfigurations nixosModules clanInternals;
+      # elided
+    };
+}
+```
+
+This is fast, simple and explicit, and doesn’t require evaluating the NixOS config. We can also displayed it in the clan-cli or clan-app.
+
+---
+
+## ✅ Option 2: Use NixOS (Only for Dynamic Hosts)
+
+If your target host depends on a **dynamic expression** (like using the machine’s evaluated FQDN), set it inside the NixOS module:
+
+```{.nix title="flake.nix" hl_lines="8"}
+{
+  # edlided
+  outputs =
+    { self, clan-core, ... }:
+    let
+      # Sometimes this attribute set is defined in clan.nix
+      clan = clan-core.lib.clan {
+        machines.jon = {config, ...}: {
+            clan.core.networking.targetHost = "jon@${config.networking.fqdn}";
+        };
+      };
+    in
+    {
+      inherit (clan.config) nixosConfigurations nixosModules clanInternals;
+      # elided
+    };
+}
+```
+
+Use this **only if the value cannot be made static**, because it’s slower and won't be displayed in the clan-cli or clan-app yet.
+
+---
+
+## 📝 TL;DR
+
+| Use Case                  | Use Inventory? | Example                          |
+| ------------------------- | -------------- | -------------------------------- |
+| Static hostname           | ✅ Yes          | `root@server.example.com`        |
+| Dynamic config expression | ❌ No           | `jon@${config.networking.fqdn}` |
+
+---
+
+## 🚀 Coming Soon: Unified Networking Module
+
+We’re working on a new networking module that will automatically do all of this for you.
+
+- Easier to use
+- Sane defaults: You’ll always be able to reach the machine — no need to worry about hostnames.
+- ✨ Migration from **either method** will be supported and simple.
+
+## Summary
+
+- Ask: *Does this hostname dynamically change based on NixOS config?*
+- If **no**, use the inventory.
+- If **yes**, then use NixOS config.

docs/site/index.md

@@ -1,36 +1,27 @@
-______________________________________________________________________
-
+---
 hide:
-
-- navigation
-- toc
-
-______________________________________________________________________
+  - navigation
+  - toc
+---
 
 # :material-home: What is Clan?
 
 [Clan](https://clan.lol/) is a peer-to-peer computer management framework that
 empowers you to **selfhost in a reliable and scalable way**.
 
-Built on NixOS, Clan provides a **declarative interface for managing machines**
-with automated [secret management](./guides/secrets.md), easy
-[mesh VPN connectivity](./guides/mesh-vpn.md), and
-[automated backups](./guides/backups.md).
+Built on NixOS, Clan provides a **declarative interface for managing machines** with automated [secret management](./guides/secrets.md), easy [mesh VPN
+connectivity](./guides/mesh-vpn.md), and [automated backups](./guides/backups.md).
 
-Whether you're running a homelab or maintaining critical computing
-infrastructure, Clan will help **reduce maintenance burden** by allowing a **git
-repository to define your whole network** of computers.
+Whether you're running a homelab or maintaining critical computing infrastructure,
+Clan will help **reduce maintenance burden** by allowing a **git repository to define your whole network** of computers.
 
-In combination with [sops-nix](https://github.com/Mic92/sops-nix),
-[nixos-anywhere](https://github.com/nix-community/nixos-anywhere) and
-[disko](https://github.com/nix-community/disko), Clan makes it possible to have
-**collaborative infrastructure**.
+In combination with [sops-nix](https://github.com/Mic92/sops-nix), [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) and [disko](https://github.com/nix-community/disko), Clan makes it possible to have **collaborative infrastructure**.
+
+At the heart of Clan are [Clan Services](./reference/clanServices/index.md) - the core
+concept that enables you to add functionality across multiple machines in your
+network. While Clan ships with essential core services, you can [create custom
+services](./guides/clanServices.md) tailored to your specific needs.
 
-At the heart of Clan are [Clan Services](./reference/clanServices/index.md) -
-the core concept that enables you to add functionality across multiple machines
-in your network. While Clan ships with essential core services, you can
-[create custom services](./guides/clanServices.md) tailored to your specific
-needs.
 
 ## :material-book: Guides
 
@@ -38,23 +29,23 @@ How-to Guides for achieving a certain goal or solving a specific issue.
 
 <div class="grid cards" markdown>
 
-- [:material-clock-fast: Getting Started](./guides/getting-started/index.md)
+-   [:material-clock-fast: Getting Started](./guides/getting-started/index.md)
 
-  ______________________________________________________________________
+    ---
 
-  Get started in less than 20 minutes!
+    Get started in less than 20 minutes!
 
-- [macOS](./guides/macos.md)
+-   [macOS](./guides/macos.md)
 
-  ______________________________________________________________________
+    ---
 
-  Using Clan to manage your macOS machines
+    Using Clan to manage your macOS machines
 
-- [Contribute](./guides/contributing/CONTRIBUTING.md)
+-   [Contribute](./guides/contributing/CONTRIBUTING.md)
 
-  ______________________________________________________________________
+    ---
 
-  How to set up a development environment
+    How to set up a development environment
 
 </div>
 
@@ -64,21 +55,21 @@ Explore the underlying principles of Clan
 
 <div class="grid cards" markdown>
 
-- [Generators](./concepts/generators.md)
+-   [Generators](./concepts/generators.md)
 
-  ______________________________________________________________________
+    ---
 
-  Learn about Generators, our way to secret management
+    Learn about Generators, our way to secret management
 
-- [Inventory](./concepts/inventory.md)
+-   [Inventory](./concepts/inventory.md)
 
-  ______________________________________________________________________
+    ---
 
-  Learn about the Inventory, a multi machine Nix interface
+    Learn about the Inventory, a multi machine Nix interface
 
 </div>
 
+
 ## Blog
 
-Visit our [Clan Blog](https://clan.lol/blog/) for the latest updates, tutorials,
-and community stories.
+Visit our [Clan Blog](https://clan.lol/blog/) for the latest updates, tutorials, and community stories.

docs/site/options.md

@@ -0,0 +1,6 @@
+---
+template: options.html
+---
+
+
+<iframe src="/options-page/" height="1000" width="100%"></iframe>

docs/site/reference/glossary.md

@@ -1,49 +1,38 @@
 # :material-api: Glossary
 
 ## clan
-
 Collection of machines interconnected in a network.
 
 ## clan-app
-
 Graphical interface for managing clans. Simpler to use than the `clan-cli`.
 
 ## clan-cli
-
 Command-line tool for managing clans.
 
 ## clanModule
-
-Module that enables configuration via the inventory. Legacy `clanModules` also
-support configuration outside the inventory.
+Module that enables configuration via the inventory.
+Legacy `clanModules` also support configuration outside the inventory.
 
 ## clanService
-
 Service defined and managed through a clan configuration.
 
 ## clanURL
-
-Flake URL-like syntax used to link to clans. Required to connect the `url-open`
-application to the `clan-app`.
+Flake URL-like syntax used to link to clans.
+Required to connect the `url-open` application to the `clan-app`.
 
 ## facts *(deprecated)*
-
-System for creating secrets and public files in a declarative way. **Note:**
-Deprecated, use `vars` instead.
+System for creating secrets and public files in a declarative way.
+**Note:** Deprecated, use `vars` instead.
 
 ## inventory
-
 JSON-like structure used to configure multiple machines.
 
 ## machine
-
 A physical computer or virtual machine.
 
 ## role
-
-Specific function assigned to a machine within a service. Allows assignment of
-sane default configurations in multi-machine services.
+Specific function assigned to a machine within a service.
+Allows assignment of sane default configurations in multi-machine services.
 
 ## vars
-
 System for creating secrets and public files in a declarative way.

docs/site/reference/index.md

@@ -1,23 +1,20 @@
 # :material-api: Overview
 
-This section of the site provides an overview of available options and commands
-within the Clan Framework.
+This section of the site provides an overview of available options and commands within the Clan Framework.
 
-______________________________________________________________________
+---
 
-- [Clan Configuration Option](/options) - for defining a Clan
+- [Clan Configuration Option](../options.md) - for defining a Clan
 - Learn how to use the [Clan CLI](./cli/index.md)
 - Explore available [services](./clanServices/index.md)
-- [NixOS Configuration Options](./clan.core/index.md) - Additional options
-  avilable on a NixOS machine.
+- [NixOS Configuration Options](./clan.core/index.md) - Additional options avilable on a NixOS machine.
 
-______________________________________________________________________
+---
 
-!!! Note This documentation is always built for the main branch. If you need
-documentation for a specific commit you can build it on your own
+!!! Note
+    This documentation is always built for the main branch.
+    If you need documentation for a specific commit you can build it on your own
 
-````
-```bash
-nix build 'git+https://git.clan.lol/clan/clan-core?ref=0324f4d4b87d932163f351e53b23b0b17f2b5e15#docs'
-```
-````
+    ```bash
+    nix build 'git+https://git.clan.lol/clan/clan-core?ref=0324f4d4b87d932163f351e53b23b0b17f2b5e15#docs'
+    ```

flake.lock

@@ -13,11 +13,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1756091210,
-        "narHash": "sha256-oEUEAZnLbNHi8ti4jY8x10yWcIkYoFc5XD+2hjmOS04=",
-        "rev": "eb831bca21476fa8f6df26cb39e076842634700d",
+        "lastModified": 1753067306,
+        "narHash": "sha256-jyoEbaXa8/MwVQ+PajUdT63y3gYhgD9o7snO/SLaikw=",
+        "rev": "18dfd42bdb2cfff510b8c74206005f733e38d8b9",
         "type": "tarball",
-        "url": "https://git.clan.lol/api/v1/repos/clan/data-mesher/archive/eb831bca21476fa8f6df26cb39e076842634700d.tar.gz"
+        "url": "https://git.clan.lol/api/v1/repos/clan/data-mesher/archive/18dfd42bdb2cfff510b8c74206005f733e38d8b9.tar.gz"
       },
       "original": {
         "type": "tarball",
@@ -31,11 +31,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1756115622,
-        "narHash": "sha256-iv8xVtmLMNLWFcDM/HcAPLRGONyTRpzL9NS09RnryRM=",
+        "lastModified": 1754971456,
+        "narHash": "sha256-p04ZnIBGzerSyiY2dNGmookCldhldWAu03y0s3P8CB0=",
         "owner": "nix-community",
         "repo": "disko",
-        "rev": "bafad29f89e83b2d861b493aa23034ea16595560",
+        "rev": "8246829f2e675a46919718f9a64b71afe3bfb22d",
         "type": "github"
       },
       "original": {
@@ -71,11 +71,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1755825449,
-        "narHash": "sha256-XkiN4NM9Xdy59h69Pc+Vg4PxkSm9EWl6u7k6D5FZ5cM=",
+        "lastModified": 1751313918,
+        "narHash": "sha256-HsJM3XLa43WpG+665aGEh8iS8AfEwOIQWk3Mke3e7nk=",
         "owner": "nix-darwin",
         "repo": "nix-darwin",
-        "rev": "8df64f819698c1fee0c2969696f54a843b2231e8",
+        "rev": "e04a388232d9a6ba56967ce5b53a8a6f713cdfcf",
         "type": "github"
       },
       "original": {
@@ -86,11 +86,11 @@
     },
     "nix-select": {
       "locked": {
-        "lastModified": 1755887746,
-        "narHash": "sha256-lzWbpHKX0WAn/jJDoCijIDss3rqYIPawe46GDaE6U3g=",
-        "rev": "92c2574c5e113281591be01e89bb9ddb31d19156",
+        "lastModified": 1745005516,
+        "narHash": "sha256-IVaoOGDIvAa/8I0sdiiZuKptDldrkDWUNf/+ezIRhyc=",
+        "rev": "69d8bf596194c5c35a4e90dd02c52aa530caddf8",
         "type": "tarball",
-        "url": "https://git.clan.lol/api/v1/repos/clan/nix-select/archive/92c2574c5e113281591be01e89bb9ddb31d19156.tar.gz"
+        "url": "https://git.clan.lol/api/v1/repos/clan/nix-select/archive/69d8bf596194c5c35a4e90dd02c52aa530caddf8.tar.gz"
       },
       "original": {
         "type": "tarball",
@@ -99,11 +99,11 @@
     },
     "nixos-facter-modules": {
       "locked": {
-        "lastModified": 1756109073,
-        "narHash": "sha256-5pjFEziluVwJ0Z50h9laKfWbDluXuA5ada05xb/QiV4=",
+        "lastModified": 1750412875,
+        "narHash": "sha256-uP9Xxw5XcFwjX9lNoYRpybOnIIe1BHfZu5vJnnPg3Jc=",
         "owner": "nix-community",
         "repo": "nixos-facter-modules",
-        "rev": "a1042c81126d9c9314c1eb1a7b89ab4d81b5dea7",
+        "rev": "14df13c84552a7d1f33c1cd18336128fbc43f920",
         "type": "github"
       },
       "original": {
@@ -115,10 +115,10 @@
     "nixpkgs": {
       "locked": {
         "lastModified": 315532800,
-        "narHash": "sha256-h8Sx4S+/0FpodZji6W9lHzwY5BcuUG85Aj3GfhvGC2o=",
-        "rev": "a650b5d0de99158323597f048667c4d914243224",
+        "narHash": "sha256-2ILJtWugqmMyZnaWnHh+5yyw8RZWbKu9rVdeWmrBVhY=",
+        "rev": "a595dde4d0d31606e19dcec73db02279db59d201",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre845298.a650b5d0de99/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre844295.a595dde4d0d3/nixexprs.tar.xz"
       },
       "original": {
         "type": "tarball",
@@ -181,11 +181,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1755934250,
-        "narHash": "sha256-CsDojnMgYsfshQw3t4zjRUkmMmUdZGthl16bXVWgRYU=",
+        "lastModified": 1754847726,
+        "narHash": "sha256-2vX8QjO5lRsDbNYvN9hVHXLU6oMl+V/PsmIiJREG4rE=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "74e1a52d5bd9430312f8d1b8b0354c92c17453e5",
+        "rev": "7d81f6fb2e19bf84f1c65135d1060d829fae2408",
         "type": "github"
       },
       "original": {

flake.nix

@@ -67,6 +67,7 @@
         clan = {
           meta.name = "clan-core";
           inventory = {
+            services = { };
             machines = {
               "test-darwin-machine" = {
                 machineClass = "darwin";
@@ -96,7 +97,6 @@
             ./nixosModules/flake-module.nix
             ./pkgs/flake-module.nix
             ./templates/flake-module.nix
-            ./pkgs/clan-cli/clan_cli/tests/flake-module.nix
           ]
         ++ [
           (if pathExists ./flakeModules/clan.nix then import ./flakeModules/clan.nix inputs.self else { })

formatter.nix

@@ -7,9 +7,6 @@
       treefmt.projectRootFile = "LICENSE.md";
       treefmt.programs.shellcheck.enable = true;
 
-      treefmt.programs.mdformat.enable = true;
-      treefmt.programs.mdformat.settings.number = true;
-      treefmt.programs.mdformat.settings.wrap = 80;
       treefmt.programs.mypy.enable = true;
       treefmt.programs.nixfmt.enable = true;
       treefmt.programs.nixfmt.package = pkgs.nixfmt-rfc-style;
@@ -40,6 +37,8 @@
         "*/gnupg-home/*"
         "*/sops/secrets/*"
         "vars/*"
+        # prettier messes up our mkdocs flavoured markdown
+        "*.md"
         "**/node_modules/*"
         "**/.mypy_cache/*"
 
@@ -97,8 +96,6 @@
         ];
         excludes = [
           "*/asciinema-player/*"
-          # prettier messes up our mkdocs flavoured markdown
-          "*.md"
         ];
       };
       treefmt.programs.mypy.directories = {

lib/README.md

@@ -11,15 +11,13 @@ Such as:
 
 ## Structure
 
-Similar to `nixpkgs/lib` this produces a recursive attribute set in a
-fixed-point. Functions within lib can depend on each other to create new
-abstractions.
+Similar to `nixpkgs/lib` this produces a recursive attribute set in a fixed-point.
+Functions within lib can depend on each other to create new abstractions.
 
 ### Conventions
 
-Note: This is not consistently enforced yet. If you start a new feature, or
-refactoring/touching existing ones, please help us to move towards the below
-illustrated.
+Note: This is not consistently enforced yet.
+If you start a new feature, or refactoring/touching existing ones, please help us to move towards the below illustrated.
 
 A single feature-set/module may be organized like this:
 
@@ -33,8 +31,8 @@ A single feature-set/module may be organized like this:
 }
 ```
 
-Every bigger feature should live in a subfolder with the feature name. It should
-contain two files:
+Every bigger feature should live in a subfolder with the feature name.
+It should contain two files:
 
 - `impl.nix`
 - `test.nix`
@@ -43,7 +41,6 @@ contain two files:
 ```
 Example filetree
 ```
-
 ```sh
 .
 ├── default.nix
@@ -72,5 +69,4 @@ Example filetree
 
 For testing we use [nix-unit](https://github.com/nix-community/nix-unit)
 
-TODO: define a helper that automatically hooks up `tests` in
-`flake.legacyPackages` and a corresponding buildable `checks` attribute
+TODO: define a helper that automatically hooks up `tests` in `flake.legacyPackages` and a corresponding buildable `checks` attribute

lib/default.nix

@@ -33,6 +33,7 @@ lib.fix (
     evalService = clanLib.callLib ./modules/inventory/distributed-service/evalService.nix { };
     # ------------------------------------
     # ClanLib functions
+    evalClan = clanLib.callLib ./modules/inventory/eval-clan-modules { };
     inventory = clanLib.callLib ./modules/inventory { };
     modules = clanLib.callLib ./modules/inventory/frontmatter { };
     test = clanLib.callLib ./test { };

lib/jsonschema/default.nix

@@ -328,7 +328,7 @@ rec {
         # To get the type of a Deferred modules we need to know the interface of the place where it is evaluated.
         # i.e. in case of a clan.service this is the interface of the service which dynamically changes depending on the service
         # We assign "type" = []
-        # This means any value is valid — or like TypeScript's unknown.
+        # This means any value is valid — or like TypeScript’s unknown.
         # We can assign the type later, when we know the exact interface.
         # tsType = "unknown" is a type that we preload for json2ts, such that it gets the correct type in typescript
         (option.type.name == "deferredModule")

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

@@ -639,7 +639,7 @@ in
 
         Exports are used to share and expose information between instances.
 
-        Define exports in the [`perInstance`](#roles.perInstance) or [`perMachine`](#perMachine) scope.
+        Define exports in the [`perInstance`](#perInstance) or [`perMachine`](#perMachine) scope.
 
         Accessing the exports:
 

lib/modules/inventory/eval-clan-modules/default.nix

@@ -0,0 +1,108 @@
+{
+  lib,
+  clanLib,
+}:
+let
+  baseModule =
+    { pkgs }:
+    # Module
+    { config, ... }:
+    {
+      imports = (import (pkgs.path + "/nixos/modules/module-list.nix"));
+      nixpkgs.pkgs = pkgs;
+      clan.core.name = "dummy";
+      system.stateVersion = config.system.nixos.release;
+      # Set this to work around a bug where `clan.core.settings.machine.name`
+      # is forced due to `networking.interfaces` being forced
+      # somewhere in the nixpkgs options
+      facter.detected.dhcp.enable = lib.mkForce false;
+    };
+
+  # This function takes a list of module names and evaluates them
+  # [ module ] -> { config, options, ... }
+  evalClanModulesLegacy =
+    {
+      modules,
+      pkgs,
+      clan-core,
+    }:
+    let
+      evaled = lib.evalModules {
+        class = "nixos";
+        modules = [
+          (baseModule { inherit pkgs; })
+          {
+            clan.core.settings.directory = clan-core;
+          }
+          clan-core.nixosModules.clanCore
+        ]
+        ++ modules;
+      };
+    in
+    # lib.warn ''
+    #   doesn't respect role specific interfaces.
+
+    #   The following {module}/default.nix file trying to be imported.
+
+    #   Modules: ${builtins.toJSON modulenames}
+
+    #   This might result in incomplete or incorrect interfaces.
+
+    #   FIX: Use evalClanModuleWithRole instead.
+    # ''
+    evaled;
+
+  /*
+    This function takes a list of module names and evaluates them
+    Returns a set of interfaces as described below:
+
+    Fn :: { ${moduleName} = Module; } -> {
+      ${moduleName} :: {
+        ${roleName}: JSONSchema
+      }
+    }
+  */
+  evalClanModulesWithRoles =
+    {
+      allModules,
+      clan-core,
+      pkgs,
+    }:
+    let
+      res = builtins.mapAttrs (
+        moduleName: module:
+        let
+          frontmatter = clanLib.modules.getFrontmatter allModules.${moduleName} moduleName;
+          roles =
+            if builtins.elem "inventory" frontmatter.features or [ ] then
+              assert lib.isPath module;
+              clan-core.clanLib.modules.getRoles "Documentation: inventory.modules" allModules moduleName
+            else
+              [ ];
+        in
+        lib.listToAttrs (
+          lib.map (role: {
+            name = role;
+            value =
+              (lib.evalModules {
+                class = "nixos";
+                modules = [
+                  (baseModule { inherit pkgs; })
+                  clan-core.nixosModules.clanCore
+                  {
+                    clan.core.settings.directory = clan-core;
+                  }
+                  # Role interface
+                  (module + "/roles/${role}.nix")
+                ];
+              }).options.clan.${moduleName} or { };
+          }) roles
+        )
+      ) allModules;
+    in
+    res;
+in
+{
+  evalClanModules = evalClanModulesLegacy;
+  inherit evalClanModulesWithRoles;
+}

lib/modules/inventory/flake-module.nix

@@ -1,8 +1,12 @@
 {
   self,
+  inputs,
   options,
   ...
 }:
+let
+  inputOverrides = self.clanLib.flake-inputs.getOverrides inputs;
+in
 {
   imports = [
     ./distributed-service/flake-module.nix
@@ -11,13 +15,16 @@
     {
       pkgs,
       lib,
+      config,
+      system,
       self',
       ...
     }:
     {
       devShells.inventory-schema = pkgs.mkShell {
         name = "clan-inventory-schema";
-        inputsFrom = [
+        inputsFrom = with config.checks; [
+          eval-lib-inventory
           self'.devShells.default
         ];
       };
@@ -44,5 +51,41 @@
           warningsAreErrors = true;
           transformOptions = self.clanLib.docs.stripStorePathsFromDeclarations;
         }).optionsJSON;
+
+      # Run: nix-unit --extra-experimental-features flakes --flake .#legacyPackages.x86_64-linux.evalTests
+      legacyPackages.evalTests-inventory = import ./tests {
+        inherit lib;
+        clan-core = self;
+        inherit (self) clanLib;
+        inherit (self.inputs) nix-darwin;
+      };
+
+      checks = {
+        eval-lib-inventory = pkgs.runCommand "tests" { nativeBuildInputs = [ pkgs.nix-unit ]; } ''
+          export HOME="$(realpath .)"
+          export NIX_ABORT_ON_WARN=1
+          nix-unit --eval-store "$HOME" \
+            --extra-experimental-features flakes \
+            --show-trace \
+            ${inputOverrides} \
+            --flake ${
+              lib.fileset.toSource {
+                root = ../../..;
+                fileset = lib.fileset.unions [
+                  ../../../flake.nix
+                  ../../../flake.lock
+                  (lib.fileset.fileFilter (file: file.name == "flake-module.nix") ../../..)
+                  ../../../flakeModules
+                  ../../../lib
+                  ../../../nixosModules/clanCore
+                  ../../../machines
+                  ../../../inventory.json
+                ];
+              }
+            }#legacyPackages.${system}.evalTests-inventory
+
+          touch $out
+        '';
+      };
     };
 }

lib/modules/inventory/frontmatter/default.nix

@@ -3,6 +3,51 @@ let
   # Trim the .nix extension from a filename
   trimExtension = name: builtins.substring 0 (builtins.stringLength name - 4) name;
 
+  jsonWithoutHeader = clanLib.jsonschema {
+    includeDefaults = true;
+    header = { };
+  };
+
+  getModulesSchema =
+    {
+      modules,
+      clan-core,
+      pkgs,
+    }:
+    lib.mapAttrs
+      (
+        _moduleName: rolesOptions:
+        lib.mapAttrs (_roleName: options: jsonWithoutHeader.parseOptions options { }) rolesOptions
+      )
+      (
+        clanLib.evalClan.evalClanModulesWithRoles {
+          allModules = modules;
+          inherit pkgs clan-core;
+        }
+      );
+
+  evalFrontmatter =
+    {
+      moduleName,
+      instanceName,
+      resolvedRoles,
+      allModules,
+    }:
+    lib.evalModules {
+      modules = [
+        (getFrontmatter allModules.${moduleName} moduleName)
+        ./interface.nix
+        {
+          constraints.imports = [
+            (lib.modules.importApply ../constraints {
+              inherit moduleName resolvedRoles instanceName;
+              allRoles = getRoles "inventory.modules" allModules moduleName;
+            })
+          ];
+        }
+      ];
+    };
+
   # For Documentation purposes only
   frontmatterOptions =
     (lib.evalModules {
@@ -74,12 +119,17 @@ let
         builtins.readDir (checkedPath)
       )
     );
+
+  checkConstraints = args: (evalFrontmatter args).config.constraints.assertions;
   getFrontmatter = _modulepath: _modulename: "clanModules are removed!";
 in
 {
   inherit
     frontmatterOptions
+    getModulesSchema
     getFrontmatter
+
+    checkConstraints
     getRoles
     ;
 }

lib/modules/inventory/schemas/default.nix

@@ -1,14 +1,29 @@
 {
   self,
+  self',
   lib,
   pkgs,
   flakeOptions,
   ...
 }:
 let
+
+  modulesSchema = self.clanLib.modules.getModulesSchema {
+    modules = self.clanModules;
+    inherit pkgs;
+    clan-core = self;
+  };
+
   jsonLib = self.clanLib.jsonschema { inherit includeDefaults; };
   includeDefaults = true;
 
+  frontMatterSchema = jsonLib.parseOptions self.clanLib.modules.frontmatterOptions { };
+
+  inventorySchema = jsonLib.parseModule ({
+    imports = [ ../../inventoryClass/interface.nix ];
+    _module.args = { inherit (self) clanLib; };
+  });
+
   opts = (flakeOptions.flake.type.getSubOptions [ "flake" ]);
   clanOpts = opts.clan.type.getSubOptions [ "clan" ];
   include = [
@@ -21,14 +36,21 @@ let
     "secrets"
     "templates"
   ];
-  clanSchemaNix = jsonLib.parseOptions (lib.filterAttrs (n: _v: lib.elem n include) clanOpts) { };
+  clanSchema = jsonLib.parseOptions (lib.filterAttrs (n: _v: lib.elem n include) clanOpts) { };
 
-  clanSchemaJson = pkgs.stdenv.mkDerivation {
+  renderSchema = pkgs.writers.writePython3Bin "render-schema" {
+    flakeIgnore = [
+      "F401"
+      "E501"
+    ];
+  } ./render_schema.py;
+
+  clan-schema-abstract = pkgs.stdenv.mkDerivation {
     name = "clan-schema-files";
     buildInputs = [ pkgs.cue ];
     src = ./.;
     buildPhase = ''
-      export SCHEMA=${builtins.toFile "clan-schema.json" (builtins.toJSON clanSchemaNix)}
+      export SCHEMA=${builtins.toFile "clan-schema.json" (builtins.toJSON clanSchema)}
       cp $SCHEMA schema.json
       # Also generate a CUE schema version that is derived from the JSON schema
       cue import -f -p compose -l '#Root:' schema.json
@@ -41,7 +63,29 @@ in
 {
   inherit
     flakeOptions
-    clanSchemaNix
-    clanSchemaJson
+    frontMatterSchema
+    clanSchema
+    inventorySchema
+    modulesSchema
+    renderSchema
+    clan-schema-abstract
     ;
+
+  # Inventory schema, with the modules schema added per role
+  inventory =
+    pkgs.runCommand "rendered"
+      {
+        buildInputs = [
+          pkgs.python3
+          self'.packages.clan-cli
+        ];
+      }
+      ''
+        export INVENTORY_SCHEMA_PATH=${builtins.toFile "inventory-schema.json" (builtins.toJSON inventorySchema)}
+        export MODULES_SCHEMA_PATH=${builtins.toFile "modules-schema.json" (builtins.toJSON modulesSchema)}
+
+        mkdir $out
+        # The python script will place the schemas in the output directory
+        exec python3 ${renderSchema}/bin/render-schema
+      '';
 }

lib/modules/inventory/schemas/render_schema.py

@@ -0,0 +1,162 @@
+"""
+Python script to join the abstract inventory schema, with the concrete clan modules
+Inventory has slots which are 'Any' type.
+We dont want to evaluate the clanModules interface in nix, when evaluating the inventory
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from clan_lib.errors import ClanError
+
+# Get environment variables
+INVENTORY_SCHEMA_PATH = Path(os.environ["INVENTORY_SCHEMA_PATH"])
+
+# { [moduleName] :: { [roleName] :: SCHEMA }}
+MODULES_SCHEMA_PATH = Path(os.environ["MODULES_SCHEMA_PATH"])
+
+OUT = os.environ.get("out")
+
+if not INVENTORY_SCHEMA_PATH:
+    msg = f"Environment variables are not set correctly: INVENTORY_SCHEMA_PATH={INVENTORY_SCHEMA_PATH}."
+    raise ClanError(msg)
+
+if not MODULES_SCHEMA_PATH:
+    msg = f"Environment variables are not set correctly: MODULES_SCHEMA_PATH={MODULES_SCHEMA_PATH}."
+    raise ClanError(msg)
+
+if not OUT:
+    msg = f"Environment variables are not set correctly: OUT={OUT}."
+    raise ClanError(msg)
+
+
+def service_roles_to_schema(
+    schema: dict[str, Any],
+    service_name: str,
+    roles: list[str],
+    roles_schemas: dict[str, dict[str, Any]],
+    # Original service properties: {'config': Schema, 'machines': Schema, 'meta': Schema, 'extraModules': Schema, ...?}
+    orig: dict[str, Any],
+) -> dict[str, Any]:
+    """
+    Add roles to the service schema
+    """
+    # collect all the roles for the service, to form a type union
+    all_roles_schema: list[dict[str, Any]] = []
+    for role_name, role_schema in roles_schemas.items():
+        role_schema["title"] = f"{module_name}-config-role-{role_name}"
+        all_roles_schema.append(role_schema)
+
+    role_schema = {}
+    for role in roles:
+        role_schema[role] = {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                **orig["roles"]["additionalProperties"]["properties"],
+                "config": {
+                    **roles_schemas.get(role, {}),
+                    "title": f"{service_name}-config-role-{role}",
+                    "type": "object",
+                    "default": {},
+                    "additionalProperties": False,
+                },
+            },
+        }
+
+    machines_schema = {
+        "type": "object",
+        "additionalProperties": {
+            "type": "object",
+            "properties": {
+                **orig["machines"]["additionalProperties"]["properties"],
+                "config": {
+                    "title": f"{service_name}-config",
+                    "oneOf": all_roles_schema,
+                    "type": "object",
+                    "default": {},
+                    "additionalProperties": False,
+                },
+            },
+        },
+    }
+
+    services["properties"][service_name] = {
+        "type": "object",
+        "additionalProperties": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                # Original inventory schema
+                **orig,
+                # Inject the roles schemas
+                "roles": {
+                    "title": f"{service_name}-roles",
+                    "type": "object",
+                    "properties": role_schema,
+                    "additionalProperties": False,
+                },
+                "machines": machines_schema,
+                "config": {
+                    "title": f"{service_name}-config",
+                    "oneOf": all_roles_schema,
+                    "type": "object",
+                    "default": {},
+                    "additionalProperties": False,
+                },
+            },
+        },
+    }
+
+    return schema
+
+
+if __name__ == "__main__":
+    print("Joining inventory schema with modules schema")
+    print(f"Inventory schema path: {INVENTORY_SCHEMA_PATH}")
+    print(f"Modules schema path: {MODULES_SCHEMA_PATH}")
+
+    modules_schema = {}
+    with Path.open(MODULES_SCHEMA_PATH) as f:
+        modules_schema = json.load(f)
+
+    inventory_schema = {}
+    with Path.open(INVENTORY_SCHEMA_PATH) as f:
+        inventory_schema = json.load(f)
+
+    services = inventory_schema["properties"]["services"]
+    original_service_props = services["additionalProperties"]["additionalProperties"][
+        "properties"
+    ].copy()
+    # Init the outer services schema
+    # Properties (service names) will be filled in the next step
+    services = {
+        "type": "object",
+        "properties": {
+            # Service names
+        },
+        "additionalProperties": False,
+    }
+
+    for module_name, roles_schemas in modules_schema.items():
+        # Add the roles schemas to the service schema
+        roles = list(roles_schemas.keys())
+        if roles:
+            services = service_roles_to_schema(
+                services,
+                module_name,
+                roles,
+                roles_schemas,
+                original_service_props,
+            )
+
+    inventory_schema["properties"]["services"] = services
+
+    outpath = Path(OUT)
+    with (outpath / "schema.json").open("w") as f:
+        json.dump(inventory_schema, f, indent=2)
+
+    with (outpath / "modules_schemas.json").open("w") as f:
+        json.dump(modules_schema, f, indent=2)

lib/modules/inventory/tests/default.nix

@@ -0,0 +1,90 @@
+{
+  clan-core,
+  nix-darwin,
+  lib,
+  clanLib,
+}:
+let
+  # TODO: Unify these tests with clan tests
+  clan =
+    m:
+    lib.evalModules {
+      specialArgs = { inherit clan-core nix-darwin clanLib; };
+      modules = [
+        clan-core.modules.clan.default
+        {
+          self = { };
+        }
+        m
+      ];
+    };
+in
+{
+  test_inventory_a =
+    let
+      eval = clan {
+        inventory = {
+          machines = {
+            A = { };
+          };
+          services = {
+            legacyModule = { };
+          };
+          modules = {
+            legacyModule = ./legacyModule;
+          };
+        };
+        directory = ./.;
+      };
+    in
+    {
+      inherit eval;
+      expr = {
+        legacyModule = lib.filterAttrs (
+          name: _: name == "isClanModule"
+        ) eval.config.clanInternals.inventoryClass.machines.A.compiledServices.legacyModule;
+      };
+      expected = {
+        legacyModule = {
+        };
+      };
+    };
+
+  test_inventory_empty =
+    let
+      eval = clan {
+        inventory = { };
+        directory = ./.;
+      };
+    in
+    {
+      # Empty inventory should return an empty module
+      expr = eval.config.clanInternals.inventoryClass.machines;
+      expected = { };
+    };
+
+  test_inventory_module_doesnt_exist =
+    let
+      eval = clan {
+        directory = ./.;
+        inventory = {
+          services = {
+            fanatasy.instance_1 = {
+              roles.default.machines = [ "machine_1" ];
+            };
+          };
+          machines = {
+            "machine_1" = { };
+          };
+        };
+      };
+    in
+    {
+      inherit eval;
+      expr = eval.config.clanInternals.inventoryClass.machines.machine_1.machineImports;
+      expectedError = {
+        type = "ThrownError";
+        msg = "ClanModule not found*";
+      };
+    };
+}

lib/modules/inventory/tests/legacyModule/README.md

@@ -0,0 +1,4 @@
+---
+features = [ "inventory" ]
+---
+Description

lib/modules/inventory/tests/legacyModule/roles/default.nix

@@ -0,0 +1,9 @@
+{
+  lib,
+  clan-core,
+  ...
+}:
+{
+  # Just some random stuff
+  options.test = lib.mapAttrs clan-core;
+}