diff --git a/docs/quickstart.md b/docs/quickstart.md
index a23bbbcd6..5efea0766 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -43,6 +43,7 @@ Absolutely, let's break down the migration step by step, explaining each action
    ```nix
    inputs.clan-core = {
      url = "git+https://git.clan.lol/clan/clan-core";
+     # Don't do this if your machines are on nixpkgs stable.
      inputs.nixpkgs.follows = "nixpkgs";
    };
    ```
@@ -75,7 +76,8 @@ Absolutely, let's break down the migration step by step, explaining each action
 
    ```nix
    nixosConfigurations = clan-core.lib.buildClan {
-       directory = ./.;
+       # this needs to point at the repository root
+       directory = self;
        specialArgs = {};
        machines = {
            example-desktop = {
diff --git a/docs/secrets-management.md b/docs/secrets-management.md
index 321d2186f..2328f822b 100644
--- a/docs/secrets-management.md
+++ b/docs/secrets-management.md
@@ -86,7 +86,7 @@ $ clan secrets machines list
 For existing machines, add their keys:
 
 ```console
-$ clan secrets machine add <machine_name> <age_key>
+$ clan secrets machines add <machine_name> <age_key>
 ```
 
 To fetch an age key from an SSH host key:
diff --git a/flake.nix b/flake.nix
index 79119ed36..7bd18b64d 100644
--- a/flake.nix
+++ b/flake.nix
@@ -31,8 +31,6 @@
         ./formatter.nix
         ./templates/flake-module.nix
 
-        ./flakeModules/clan-config.nix
-
         ./pkgs/flake-module.nix
 
         ./lib/flake-module.nix
diff --git a/flakeModules/clan-config.nix b/flakeModules/clan-config.nix
deleted file mode 100644
index 236d22592..000000000
--- a/flakeModules/clan-config.nix
+++ /dev/null
@@ -1,42 +0,0 @@
-{ ... } @ clanCore: {
-  flake.flakeModules.clan-config = { self, inputs, ... }:
-    let
-
-      # take the default nixos configuration
-      options = self.nixosConfigurations.default.options;
-
-      # this is actually system independent as it uses toFile
-      docs = inputs.nixpkgs.legacyPackages.x86_64-linux.nixosOptionsDoc {
-        inherit options;
-      };
-
-      optionsJSONFile = docs.optionsJSON.options;
-
-      warnIfNoDefaultConfig = return:
-        if ! self ? nixosConfigurations.default
-        then
-          builtins.trace
-            "WARNING: .#nixosConfigurations.default could not be found. Please define it."
-            return
-        else return;
-
-    in
-    {
-      flake.clanOptions = warnIfNoDefaultConfig optionsJSONFile;
-
-      flake.clanSettings = self + /clan-settings.json;
-
-      perSystem = { pkgs, ... }: {
-        devShells.clan-config = pkgs.mkShell {
-          packages = [
-            clanCore.config.flake.packages.${pkgs.system}.clan-cli
-          ];
-          shellHook = ''
-            export CLAN_OPTIONS_FILE=$(nix eval --raw .#clanOptions)
-            export XDG_DATA_DIRS="${clanCore.config.flake.packages.${pkgs.system}.clan-cli}/share''${XDG_DATA_DIRS:+:$XDG_DATA_DIRS}"
-            export fish_complete_path="${clanCore.config.flake.packages.${pkgs.system}.clan-cli}/share/fish/vendor_completions.d''${fish_complete_path:+:$fish_complete_path}"
-          '';
-        };
-      };
-    };
-}
diff --git a/nixosModules/clanCore/secrets/default.nix b/nixosModules/clanCore/secrets/default.nix
index 700f5d078..44fa757de 100644
--- a/nixosModules/clanCore/secrets/default.nix
+++ b/nixosModules/clanCore/secrets/default.nix
@@ -62,7 +62,8 @@
                   default = "machines/${config.clanCore.machineName}/facts/${fact.config._module.args.name}";
                 };
                 value = lib.mkOption {
-                  default = builtins.readFile "${config.clanCore.clanDir}/fact.config.path";
+                  defaultText = lib.literalExpression "\${config.clanCore.clanDir}/\${fact.config.path}";
+                  default = builtins.readFile "${config.clanCore.clanDir}/${fact.config.path}";
                 };
               };
             }));
diff --git a/pkgs/clan-cli/clan_cli/__init__.py b/pkgs/clan-cli/clan_cli/__init__.py
index 0eb6dd527..f67bee800 100644
--- a/pkgs/clan-cli/clan_cli/__init__.py
+++ b/pkgs/clan-cli/clan_cli/__init__.py
@@ -1,5 +1,4 @@
 import argparse
-import os
 import sys
 from types import ModuleType
 from typing import Optional
@@ -22,10 +21,8 @@ def create_parser(prog: Optional[str] = None) -> argparse.ArgumentParser:
     parser_create = subparsers.add_parser("create", help="create a clan flake")
     create.register_parser(parser_create)
 
-    # DISABLED: this currently crashes if a flake does not define .#clanOptions
-    if os.environ.get("CLAN_OPTIONS_FILE") is not None:
-        parser_config = subparsers.add_parser("config", help="set nixos configuration")
-        config.register_parser(parser_config)
+    parser_config = subparsers.add_parser("config", help="set nixos configuration")
+    config.register_parser(parser_config)
 
     parser_ssh = subparsers.add_parser("ssh", help="ssh to a remote machine")
     ssh_cli.register_parser(parser_ssh)
diff --git a/pkgs/clan-cli/clan_cli/config/__init__.py b/pkgs/clan-cli/clan_cli/config/__init__.py
index d81fbc2ca..1a3c0fbda 100644
--- a/pkgs/clan-cli/clan_cli/config/__init__.py
+++ b/pkgs/clan-cli/clan_cli/config/__init__.py
@@ -9,6 +9,7 @@ from typing import Any, Optional, Type
 
 from clan_cli.dirs import get_clan_flake_toplevel
 from clan_cli.errors import ClanError
+from clan_cli.machines.folders import machine_settings_file
 from clan_cli.nix import nix_eval
 
 script_dir = Path(__file__).parent
@@ -166,7 +167,6 @@ def get_or_set_option(args: argparse.Namespace) -> None:
         print(read_machine_option_value(args.machine, args.option))
     else:
         # load options
-        print(args.options_file)
         if args.options_file is None:
             options = options_for_machine(machine_name=args.machine)
         else:
@@ -174,8 +174,8 @@ def get_or_set_option(args: argparse.Namespace) -> None:
                 options = json.load(f)
         # compute settings json file location
         if args.settings_file is None:
-            flake = get_clan_flake_toplevel()
-            settings_file = flake / "machines" / f"{args.machine}.json"
+            get_clan_flake_toplevel()
+            settings_file = machine_settings_file(args.machine)
         else:
             settings_file = args.settings_file
         # set the option with the given value
@@ -286,7 +286,7 @@ def register_parser(
     # add single positional argument for the option (e.g. "foo.bar")
     parser.add_argument(
         "option",
-        help="Option to configure",
+        help="Option to read or set",
         type=str,
     )
 
diff --git a/pkgs/clan-cli/clan_cli/config/machine.py b/pkgs/clan-cli/clan_cli/config/machine.py
index 1e3b29a13..cad6b5082 100644
--- a/pkgs/clan-cli/clan_cli/config/machine.py
+++ b/pkgs/clan-cli/clan_cli/config/machine.py
@@ -12,7 +12,7 @@ from clan_cli.nix import nix_eval
 
 
 def config_for_machine(machine_name: str) -> dict:
-    # read the config from a json file located at {flake}/machines/{machine_name}.json
+    # read the config from a json file located at {flake}/machines/{machine_name}/settings.json
     if not machine_folder(machine_name).exists():
         raise HTTPException(
             status_code=404,
@@ -26,7 +26,7 @@ def config_for_machine(machine_name: str) -> dict:
 
 
 def set_config_for_machine(machine_name: str, config: dict) -> None:
-    # write the config to a json file located at {flake}/machines/{machine_name}.json
+    # write the config to a json file located at {flake}/machines/{machine_name}/settings.json
     if not machine_folder(machine_name).exists():
         raise HTTPException(
             status_code=404,
diff --git a/pkgs/clan-cli/default.nix b/pkgs/clan-cli/default.nix
index 1f43eb45b..f41152fff 100644
--- a/pkgs/clan-cli/default.nix
+++ b/pkgs/clan-cli/default.nix
@@ -22,9 +22,6 @@
 , ui-assets
 }:
 let
-  # This provides dummy options for testing clan config and prevents it from
-  # evaluating the flake .#
-  CLAN_OPTIONS_FILE = ./clan_cli/config/jsonschema/options.json;
 
   dependencies = [
     argcomplete # optional dependency: if not enabled, shell completion will not work
@@ -54,9 +51,9 @@ let
   '';
   nixpkgs = runCommand "nixpkgs" { nativeBuildInputs = [ pkgs.nix ]; } ''
     mkdir $out
-    mkdir -p $out/unfree                                                                       
-    cat > $out/unfree/default.nix <<EOF                                                        
-    import "${pkgs.path}" { config = { allowUnfree = true; overlays = []; }; }                 
+    mkdir -p $out/unfree
+    cat > $out/unfree/default.nix <<EOF
+    import "${pkgs.path}" { config = { allowUnfree = true; overlays = []; }; }
     EOF
     cat > $out/flake.nix << EOF
     {
@@ -81,8 +78,6 @@ python3.pkgs.buildPythonPackage {
   src = source;
   format = "pyproject";
 
-  inherit CLAN_OPTIONS_FILE;
-
   nativeBuildInputs = [
     setuptools
     installShellFiles
@@ -93,12 +88,11 @@ python3.pkgs.buildPythonPackage {
     {
       nativeBuildInputs = [ age zerotierone bubblewrap sops nix openssh rsync stdenv.cc ];
     } ''
-    export CLAN_OPTIONS_FILE="${CLAN_OPTIONS_FILE}"
     cp -r ${source} ./src
     chmod +w -R ./src
     cd ./src
 
-    export NIX_STATE_DIR=$TMPDIR/nix IN_NIX_SANDBOX=1 
+    export NIX_STATE_DIR=$TMPDIR/nix IN_NIX_SANDBOX=1
     ${checkPython}/bin/python -m pytest -m "not impure" -s ./tests
     touch $out
   '';
diff --git a/pkgs/clan-cli/shell.nix b/pkgs/clan-cli/shell.nix
index f0ff0d7d0..f95340cbf 100644
--- a/pkgs/clan-cli/shell.nix
+++ b/pkgs/clan-cli/shell.nix
@@ -20,9 +20,6 @@ mkShell {
     pythonWithDeps
   ];
   # sets up an editable install and add enty points to $PATH
-  # This provides dummy options for testing clan config and prevents it from
-  # evaluating the flake .#
-  CLAN_OPTIONS_FILE = ./clan_cli/config/jsonschema/options.json;
   PYTHONPATH = "${pythonWithDeps}/${pythonWithDeps.sitePackages}";
   PYTHONBREAKPOINT = "ipdb.set_trace";
 
diff --git a/pkgs/clan-cli/tests/test_flake/flake.nix b/pkgs/clan-cli/tests/test_flake/flake.nix
index 3ba6f3f61..23d2a672f 100644
--- a/pkgs/clan-cli/tests/test_flake/flake.nix
+++ b/pkgs/clan-cli/tests/test_flake/flake.nix
@@ -6,8 +6,8 @@
     nixosConfigurations.machine1 = inputs.nixpkgs.lib.nixosSystem {
       modules = [
         ./nixosModules/machine1.nix
-        (if builtins.pathExists ./machines/machine1.json
-        then builtins.fromJSON (builtins.readFile ./machines/machine1.json)
+        (if builtins.pathExists ./machines/machine1/settings.json
+        then builtins.fromJSON (builtins.readFile ./machines/machine1/settings.json)
         else { })
         {
           nixpkgs.hostPlatform = "x86_64-linux";