docs: Move age plugins to vars/sops backend group. Improve age plugin documentation

docs/mkdocs.yml

@@ -62,12 +62,13 @@ nav:
           - Convert Existing NixOS Config: guides/getting-started/convert-flake.md
       - ClanServices: guides/clanServices.md
       - Vars:
-          - Overview: guides/vars-overview.md
-          - Getting Started: guides/vars-backend.md
-          - Concepts: guides/vars-concepts.md
-          - Advanced Examples: guides/vars-advanced-examples.md
-          - Troubleshooting: guides/vars-troubleshooting.md
-      - Age Plugins: guides/age-plugins.md
+          - Overview: guides/vars/vars-overview.md
+          - Getting Started: guides/vars/vars-backend.md
+          - Concepts: guides/vars/vars-concepts.md
+          - Sops Backend:
+              - Yubikeys & Age Plugins: guides/vars/sops/age-plugins.md
+          - Advanced Examples: guides/vars/vars-advanced-examples.md
+          - Troubleshooting: guides/vars/vars-troubleshooting.md
       - Backup & Restore: guides/backups.md
       - Disk Encryption: guides/disk-encryption.md
       - Secrets management: guides/secrets.md
@@ -223,4 +224,4 @@ plugins:
   - redoc-tag
   - redirects:
       redirect_maps:
-        guides/getting-started/secrets.md: guides/vars-overview.md
+        guides/getting-started/secrets.md: guides/vars/vars-overview.md

docs/nix/options/flake-module.nix

@@ -205,7 +205,9 @@
       # };
 
       packages = {
-        docs-options = privateInputs.nuschtos.packages.${pkgs.stdenv.hostPlatform.system}.mkMultiSearch {
+        docs-options =
+          if privateInputs ? nuschtos then
+            privateInputs.nuschtos.packages.${pkgs.stdenv.hostPlatform.system}.mkMultiSearch {
               inherit baseHref;
               title = "Clan Options";
               # scopes = mapAttrsToList mkScope serviceModules;
@@ -220,9 +222,13 @@
                   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/";
-
                 }
               ];
+            }
+          else
+            pkgs.stdenv.mkDerivation {
+              name = "empty";
+              buildCommand = "echo 'This is an empty derivation' > $out";
             };
       };
     };

docs/site/guides/age-plugins.md

@@ -1,59 +0,0 @@
-## Using Age Plugins
-
-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**.
-
-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:
-
-```title="~/.config/sops/age/keys.txt"
-# public key: age1zdy49ek6z60q9r34vf5mmzkx6u43pr9haqdh5lqdg7fh5tpwlfwqea356l
-AGE-PLUGIN-FIDO2-HMAC-1QQPQZRFR7ZZ2WCV...
-```
-
-!!! 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....`
-
-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"
-{
-  inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-  inputs.nixpkgs.follows = "clan-core/nixpkgs";
-
-  outputs =
-    { self, clan-core, ... }:
-    let
-      # Sometimes this attribute set is defined in clan.nix
-      clan = clan-core.lib.clan {
-        inherit self;
-
-        meta.name = "myclan";
-
-        # Add Yubikey and FIDO2 HMAC plugins
-        # Note: the plugins listed here must be available in nixpkgs.
-        secrets.age.plugins = [
-          "age-plugin-yubikey"
-          "age-plugin-fido2-hmac"
-        ];
-
-        machines = {
-          # elided for brevity
-        };
-      };
-    in
-    {
-      inherit (clan) nixosConfigurations nixosModules clanInternals;
-
-      # elided for brevity
-    };
-}
-```

docs/site/guides/macos.md

@@ -7,7 +7,7 @@ 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
-- Support for [vars](../guides/vars-overview.md)
+- Support for [vars](../guides/vars/vars-overview.md)
 
 ## Add Your Machine to Your Clan Flake
 

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

@@ -3,7 +3,7 @@
 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`](../../guides/vars-overview.md) backend.
+to the [`vars`](../../guides/vars/vars-overview.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.
 

docs/site/guides/secrets.md

@@ -1,5 +1,5 @@
-This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars-overview.md).
-Under most circumstances you should use [Vars](../guides/vars-overview.md) directly instead.
+This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars/vars-overview.md).
+Under most circumstances you should use [Vars](../guides/vars/vars-overview.md) directly instead.
 
 Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool.
 

docs/site/guides/vars/sops/age-plugins.md

@@ -0,0 +1,85 @@
+# Using Age Plugins with Clan Vars
+
+This guide explains how to set up YubiKey and other plugins for `clan vars` secrets.
+
+By default the `clan vars` subcommand uses the `age` encryption tool, which supports various plugins.
+
+---
+
+## Supported Age Plugins
+
+Below is a [list of popular `age` plugins](https://github.com/FiloSottile/awesome-age?tab=readme-ov-file#plugins) you can use with Clan. (Last updated: **September 12, 2025**)
+
+- ⭐️ [**age-plugin-yubikey**](https://github.com/str4d/age-plugin-yubikey): YubiKey (and other PIV tokens) plugin.
+-  [**age-plugin-se**](https://github.com/remko/age-plugin-se): Apple Secure Enclave plugin.
+- 🧪 [**age-plugin-tpm**](https://github.com/Foxboron/age-plugin-tpm): TPM 2.0 plugin.
+- 🧪 [**age-plugin-tkey**](https://github.com/quite/age-plugin-tkey): Tillitis TKey plugin.
+   [**age-plugin-trezor**](https://github.com/romanz/trezor-agent/blob/master/doc/README-age.md): Hardware wallet plugin (TREZOR, Ledger, etc.).
+- 🧪 [**age-plugin-sntrup761x25519**](https://github.com/keisentraut/age-plugin-sntrup761x25519): Post-quantum hybrid plugin (NTRU Prime + X25519).
+- 🧪 [**age-plugin-fido**](https://github.com/riastradh/age-plugin-fido): Prototype symmetric encryption plugin for FIDO2 keys.
+- 🧪 [**age-plugin-fido2-hmac**](https://github.com/olastor/age-plugin-fido2-hmac): FIDO2 plugin with PIN support.
+- 🧪 [**age-plugin-sss**](https://github.com/olastor/age-plugin-sss): Shamir's Secret Sharing (SSS) plugin.
+- 🧪 [**age-plugin-amnesia**](https://github.com/cedws/amnesia/blob/master/README.md#age-plugin-experimental): Adds Q&A-based identity wrapping.
+
+> **Note:** Plugins marked with 🧪 are experimental. Plugins marked with ⭐️ are official.
+
+---
+
+## Using Plugin-Generated Keys
+
+If you want to use `fido2 tokens` to encrypt your secret instead of the normal age secret key then you need to prefix your age secret key with the corresponding plugin name. In our case we want to use the `age-plugin-fido2-hmac` plugin so we replace `AGE-SECRET-KEY` with `AGE-PLUGIN-FIDO2-HMAC`.
+
+??? tip
+    - On Linux the age secret key is located at `~/.config/sops/age/keys.txt`
+    - On macOS it is located at `/Users/admin/Library/Application Support/sops/age/keys.txt`
+
+**Before**:
+  ```hl_lines="2"
+  # public key: age1zdy49ek6z60q9r34vf5mmzkx6u43pr9haqdh5lqdg7fh5tpwlfwqea356l
+  AGE-SECRET-KEY-1QQPQZRFR7ZZ2WCV...
+  ```
+
+  **After**:
+```hl_lines="2"
+# public key: age1zdy49ek6z60q9r34vf5mmzkx6u43pr9haqdh5lqdg7fh5tpwlfwqea356l
+AGE-PLUGIN-FIDO2-HMAC-1QQPQZRFR7ZZ2WCV...
+```
+
+
+
+## Configuring Plugins in `flake.nix`
+
+To use `age` plugins with Clan, you need to configure them in your `flake.nix` file. Here’s an example:
+
+```nix title="flake.nix"
+{
+  inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
+  inputs.nixpkgs.follows = "clan-core/nixpkgs";
+
+  outputs = { self, clan-core, ... }:
+  let
+    # Define Clan configuration
+    clan = clan-core.lib.clan {
+      inherit self;
+
+      meta.name = "myclan";
+
+      # Add YubiKey and FIDO2 HMAC plugins
+      # Note: Plugins must be available in nixpkgs.
+      secrets.age.plugins = [
+        "age-plugin-yubikey"
+        "age-plugin-fido2-hmac"
+      ];
+
+      machines = {
+        # Machine configurations (elided for brevity)
+      };
+    };
+  in
+  {
+    inherit (clan) nixosConfigurations nixosModules clanInternals;
+
+    # Additional configurations (elided for brevity)
+  };
+}
+```

docs/site/guides/vars/vars-backend.md

@@ -1,6 +1,6 @@
 The `clan vars` subcommand is a powerful tool for managing machine-specific variables in a declarative and reproducible way. This guide will walk you through its usage, from setting up a generator to sharing and updating variables across machines.
 
-For a detailed API reference, see the [vars module documentation](../reference/clan.core/vars.md).
+For a detailed API reference, see the [vars module documentation](../../reference/clan.core/vars.md).
 
 In this guide, you will learn how to:
 

docs/site/guides/vars/vars-overview.md

@@ -141,5 +141,5 @@ clan machines update my-machine
 
 ## Migration from Facts
 
-If you're currently using the legacy facts system, see our [Migration Guide](migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
+If you're currently using the legacy facts system, see our [Migration Guide](../migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
 

docs/site/index.md

@@ -55,7 +55,7 @@ Explore the underlying principles of Clan
 
 <div class="grid cards" markdown>
 
--   [Vars](./guides/vars-overview.md)
+-   [Vars](./guides/vars/vars-overview.md)
 
     ---
 

flake.nix

@@ -51,7 +51,7 @@
         ;
 
       privateInputs =
-        if builtins.pathExists (./. + ".skip-private-inputs") then
+        if builtins.pathExists (./. + "/.skip-private-inputs") then
           { }
         else
           (import ./devFlake/flake-compat.nix {