diff --git a/modules/flake-parts/all-modules.nix b/modules/flake-parts/all-modules.nix
index 3a99a30d9..ee76f2f20 100644
--- a/modules/flake-parts/all-modules.nix
+++ b/modules/flake-parts/all-modules.nix
@@ -31,7 +31,13 @@ in {
   };
 
   # generates future flake outputs: `modules.<kind>.<module-name>`
-  config.flake.modules = lib.mapAttrs (kind: _: mapModules kind) moduleKinds;
+  config.flake.modules =
+    let modules = lib.mapAttrs (kind: _: mapModules kind) moduleKinds;
+    in modules // {
+      flake-parts = modules.flake-parts // {
+        all-modules = { imports = flakePartsModules; _class = "flake-parts"; };
+      };
+    };
 
   # comapt to current schema: `nixosModules` / `darwinModules`
   config.flake.nixosModules = config.flake.modules.nixos or {};
diff --git a/modules/flake-parts/writers.nix b/modules/flake-parts/writers.nix
index 4a37adeb8..84e7cafc7 100644
--- a/modules/flake-parts/writers.nix
+++ b/modules/flake-parts/writers.nix
@@ -1,5 +1,5 @@
-{
-  perSystem = {
+{ flake-parts-lib, ... }: {
+  options.perSystem = flake-parts-lib.mkPerSystemOption ({
     config,
     lib,
     pkgs,
@@ -9,10 +9,25 @@
   in {
     options.writers = {
       writePureShellScript = lib.mkOption {
-        type = lib.types.functionTo lib.types.anything;
+        type = lib.types.functionTo (lib.types.functionTo lib.types.package);
+        description = ''
+          Create a script that runs in a `pure` environment, in the sense that:
+            - `PATH` only contains exactly the packages passed via the `PATH` arg
+            - `NIX_PATH` is set to the path of the current `pkgs`
+            - `TMPDIR` is set up and cleaned up even if the script fails
+            - out, if set, is kept as-is
+            - all environment variables are unset, except:
+            - the ones listed in `keepVars` below
+            - ones listed via the `KEEP_VARS` variable
+            - the behavior is similar to `nix-shell --pure`
+        '';
       };
       writePureShellScriptBin = lib.mkOption {
-        type = lib.types.functionTo lib.types.anything;
+        type = lib.types.functionTo (lib.types.functionTo (lib.types.functionTo lib.types.package));
+        description = ''
+          Creates a script in a `bin/` directory in the output; suitable for use with `lib.makeBinPath`, etc.
+          See {option}`writers.writePureShellScript`
+        '';
       };
     };
 
@@ -23,5 +38,5 @@
         writePureShellScriptBin
         ;
     };
-  };
+  });
 }
diff --git a/pkgs/writers/default.nix b/pkgs/writers/default.nix
index 45e856880..33426bfa0 100644
--- a/pkgs/writers/default.nix
+++ b/pkgs/writers/default.nix
@@ -8,20 +8,11 @@
   writeScriptBin,
   ...
 }: let
-  /*
-  create a script that runs in a `pure` environment, in the sense that:
-  - PATH only contains exactly the packages passed via the PATH arg
-  - NIX_PATH is set to the path of the current `pkgs`
-  - TMPDIR is set up and cleaned up even if the script fails
-  - out, if set, is kept as-is
-  - all environment variables are unset, except:
-  - the ones listed in `keepVars` below
-  - ones listed via the KEEP_VARS variable
-  - the behavior is similar to `nix-shell --pure`
-  */
+  # Docs at modules/flake-parts/writers.nix
   writePureShellScript = PATH: script:
     writeScript "script.sh" (mkScript PATH script);
 
+  # Docs at modules/flake-parts/writers.nix
   writePureShellScriptBin = binName: PATH: script:
     writeScriptBin binName (mkScript PATH script);