diff --git a/checks/flake-module.nix b/checks/flake-module.nix
index a6de83757..c783ebaca 100644
--- a/checks/flake-module.nix
+++ b/checks/flake-module.nix
@@ -6,6 +6,7 @@
     ./flash/flake-module.nix
     ./impure/flake-module.nix
     ./installation/flake-module.nix
+    ./nixos-documentation/flake-module.nix
   ];
   perSystem =
     {
diff --git a/checks/nixos-documentation/flake-module.nix b/checks/nixos-documentation/flake-module.nix
new file mode 100644
index 000000000..743d97c19
--- /dev/null
+++ b/checks/nixos-documentation/flake-module.nix
@@ -0,0 +1,26 @@
+{ self, ... }:
+let
+  documentationModule = {
+    # This is how some downstream users currently generate documentation
+    # If this breaks notify them via matrix since we spent ~5 hrs for bughunting last time.
+    documentation.nixos.enable = true;
+    documentation.nixos.extraModules = [
+      self.nixosModules.clanCore
+      # This is the only option that is not part of the
+      # module because it is usually set by flake-parts
+      { clan.core.clanDir = ./.; }
+    ];
+  };
+in
+{
+  clan = {
+    machines.test-documentation = {
+      # Dummy file system
+      fileSystems."/".device = "/dev/null";
+      boot.loader.grub.device = "/dev/null";
+      imports = [
+        documentationModule
+      ];
+    };
+  };
+}
diff --git a/flake.lock b/flake.lock
index e717d4f6b..1b13545c0 100644
--- a/flake.lock
+++ b/flake.lock
@@ -40,6 +40,22 @@
         "type": "github"
       }
     },
+    "nixos-facter-modules": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1724681057,
+        "narHash": "sha256-wxx2Sh/urE3sKY/1v3tmrWTNMIQ3RoJtd7bcuqVpY2Y=",
+        "owner": "numtide",
+        "repo": "nixos-facter-modules",
+        "rev": "55088bf19810d23ca7cb86fb71516c95d97f035b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "nixos-facter-modules",
+        "type": "github"
+      }
+    },
     "nixos-images": {
       "inputs": {
         "nixos-stable": [],
@@ -81,6 +97,7 @@
       "inputs": {
         "disko": "disko",
         "flake-parts": "flake-parts",
+        "nixos-facter-modules": "nixos-facter-modules",
         "nixos-images": "nixos-images",
         "nixpkgs": "nixpkgs",
         "sops-nix": "sops-nix",
diff --git a/flake.nix b/flake.nix
index 821ad2ab4..74d392a6f 100644
--- a/flake.nix
+++ b/flake.nix
@@ -18,16 +18,11 @@
     treefmt-nix.url = "github:numtide/treefmt-nix";
     treefmt-nix.inputs.nixpkgs.follows = "nixpkgs";
 
-    #nixos-facter-modules.url = "github:numtide/nixos-facter-modules";
-    #nixos-facter-modules.inputs.nixpkgs.follows = "nixpkgs";
-    #nixos-facter-modules.inputs.systems.follows = "systems";
-    #nixos-facter-modules.inputs.blueprint.follows = "blueprint";
-    #nixos-facter-modules.inputs.treefmt-nix.follows = "treefmt-nix";
-    # Pinned input for nixos-facter-modules
-    # Allows downstream flakes to .follow override the input
-    #blueprint.url = "github:numtide/blueprint";
-    #blueprint.inputs.nixpkgs.follows = "nixpkgs";
-    #blueprint.inputs.systems.follows = "systems";
+    nixos-facter-modules.url = "github:numtide/nixos-facter-modules";
+    # TODO: remove this once the upstream doesnt have dependencies
+    nixos-facter-modules.flake = false;
+    # nixos-facter-modules.inputs.nixpkgs.follows = "nixpkgs";
+
   };
 
   outputs =
diff --git a/lib/build-clan/module.nix b/lib/build-clan/module.nix
index 947d63ed9..22b154a3b 100644
--- a/lib/build-clan/module.nix
+++ b/lib/build-clan/module.nix
@@ -67,13 +67,13 @@ let
           facterJson = "${directory}/machines/${name}/facter.json";
           hwConfig = "${directory}/machines/${name}/hardware-configuration.nix";
 
+          facterModules = lib.optionals (builtins.pathExists facterJson) [
+            "${clan-core.inputs.nixos-facter-modules}/modules/nixos/facter.nix"
+            { config.facter.reportPath = facterJson; }
+          ];
         in
-        #facterModules = lib.optionals (builtins.pathExists facterJson) [
-        #  clan-core.inputs.nixos-facter-modules.nixosModules.facter
-        #  { config.facter.reportPath = facterJson; }
-        #];
         (machineImports settings)
-        #++ facterModules
+        ++ facterModules
         ++ [
           {
             # Autoinclude configuration.nix and hardware-configuration.nix
diff --git a/nixosModules/clanCore/inventory/interface.nix b/nixosModules/clanCore/inventory/interface.nix
index 895a15994..ddddd9fd5 100644
--- a/nixosModules/clanCore/inventory/interface.nix
+++ b/nixosModules/clanCore/inventory/interface.nix
@@ -14,22 +14,49 @@ let
   #   };
   # }
   instanceOptions = lib.types.submodule {
-    options.roles = lib.mkOption { type = lib.types.attrsOf machinesList; };
+    options.roles = lib.mkOption {
+      description = ''
+        Configuration for a service instance.
+
+        Specific roles describe the membership of foreign machines.
+
+        ```nix
+        { # Configuration for an instance
+          roles.<roleName>.machines = [ # List of machines ];
+        }
+        ```
+      '';
+
+      type = lib.types.attrsOf machinesList;
+    };
   };
 
-  # {
-  #   machines = [
-  #     "camina_machine"
-  #     "vi_machine"
-  #     "vyr_machine"
-  #   ];
-  # }
   machinesList = lib.types.submodule {
-    options.machines = lib.mkOption { type = lib.types.listOf lib.types.str; };
+    options.machines = lib.mkOption {
+      description = ''
+        List of machines that are part of a role.
+
+        ```nix
+        { # Configuration for an instance
+          roles.<roleName>.machines = [ # List of machines ];
+        }
+        ```
+      '';
+      type = lib.types.listOf lib.types.str;
+    };
   };
 in
 {
   options.clan.inventory.services = lib.mkOption {
+    description = ''
+      Configuration for each inventory service.
+
+      Each service can have multiple instances as follows:
+
+      ```
+      {serviceName}.{instancename} = { # Configuration for an instance }
+      ```
+    '';
     type = lib.types.attrsOf (lib.types.attrsOf instanceOptions);
   };
 }
diff --git a/nixosModules/clanCore/meta/interface.nix b/nixosModules/clanCore/meta/interface.nix
index aef373d57..6a01ad56f 100644
--- a/nixosModules/clanCore/meta/interface.nix
+++ b/nixosModules/clanCore/meta/interface.nix
@@ -3,7 +3,16 @@ let
   optStr = lib.types.nullOr lib.types.str;
 in
 {
-  options.clan.meta.name = lib.mkOption { type = lib.types.str; };
-  options.clan.meta.description = lib.mkOption { type = optStr; };
-  options.clan.meta.icon = lib.mkOption { type = optStr; };
+  options.clan.meta.name = lib.mkOption {
+    description = "The name of the clan";
+    type = lib.types.str;
+  };
+  options.clan.meta.description = lib.mkOption {
+    description = "The description of the clan";
+    type = optStr;
+  };
+  options.clan.meta.icon = lib.mkOption {
+    description = "The location of the clan icon";
+    type = optStr;
+  };
 }
diff --git a/nixosModules/clanCore/metadata.nix b/nixosModules/clanCore/metadata.nix
index d37f62c75..2e5fb7188 100644
--- a/nixosModules/clanCore/metadata.nix
+++ b/nixosModules/clanCore/metadata.nix
@@ -45,8 +45,11 @@
     };
     clanDir = lib.mkOption {
       type = lib.types.path;
-      # TODO: @DavHau: before we can remove this, we need to make sure that Palo's config case works
-      default = ./.;
+      # documentation.nixos.extraModules = [
+      #   ...
+      #   clan-core.nixosModules.clanCore
+      #   { clan.core.clanDir = ./path/to/flake; }
+      # ];
       description = ''
         the location of the flake repo, used to calculate the location of facts and secrets
       '';