diff --git a/dev/default.nix b/dev/default.nix
index d6d28a4..6fa49dd 100644
--- a/dev/default.nix
+++ b/dev/default.nix
@@ -4,6 +4,7 @@ let
   self = {
     inherit (flake) inputs;
     outPath = ../.; # used by pre-commit module, etc
+    outputs = self.config.flake;
   } //
   fmc-lib.evalFlakeModule
     { inherit self; }
diff --git a/dev/flake-module.nix b/dev/flake-module.nix
index 78777a2..a621da9 100644
--- a/dev/flake-module.nix
+++ b/dev/flake-module.nix
@@ -30,25 +30,20 @@
     };
 
   };
-  flake = {
-    # Because of ./README.md, we can't use the built-in flake support, including
-    # the `effects` flake attribute. We have to define `herculesCI` ourselves.
-    options.herculesCI = lib.mkOption { type = lib.types.raw; };
-    config.herculesCI = { branch, ... }: {
-      onPush.default.outputs = {
-        inherit (config.flake) packages checks;
-        effects =
-          withSystem "x86_64-linux" ({ config, pkgs, effects, ... }: {
-            netlifyDeploy = effects.netlifyDeploy {
-              content = config.packages.siteContent;
-              secretName = "default-netlify";
-              siteId = "29a153b1-3698-433c-bc73-62415efb8117";
-              productionDeployment = branch == "main";
-            };
-          });
-      };
+  herculesCI = herculesCI@{ config, ... }: {
+    onPush.default.outputs = {
+      effects =
+        withSystem "x86_64-linux" ({ config, pkgs, hci-effects, ... }: {
+          netlifyDeploy = hci-effects.netlifyDeploy {
+            content = config.packages.siteContent;
+            secretName = "default-netlify";
+            siteId = "29a153b1-3698-433c-bc73-62415efb8117";
+            productionDeployment = herculesCI.config.repo.branch == "main";
+          };
+        });
     };
-
+  };
+  flake = {
     # for repl exploration / debug
     config.config = config;
     options.mySystem = lib.mkOption { default = config.allSystems.${builtins.currentSystem}; };
diff --git a/dev/flake.lock b/dev/flake.lock
index c3d7fa4..60bc8b0 100644
--- a/dev/flake.lock
+++ b/dev/flake.lock
@@ -1,5 +1,44 @@
 {
   "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1666885127,
+        "narHash": "sha256-uXA/3lhLhwOTBMn9a5zJODKqaRT+SuL5cpEmOz2ULoo=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "0e101dbae756d35a376a5e1faea532608e4a4b9a",
+        "type": "github"
+      },
+      "original": {
+        "id": "flake-parts",
+        "type": "indirect"
+      }
+    },
+    "flake-parts_2": {
+      "inputs": {
+        "nixpkgs": [
+          "hercules-ci-effects",
+          "hercules-ci-agent",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1657102481,
+        "narHash": "sha256-62Fuw8JgPub38OdgNefkIKOodM9nC3M0AG6lS+7smf4=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "608ed3502263d6f4f886d75c48fc2b444a4ab8d8",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "locked": {
         "lastModified": 1619345332,
@@ -15,16 +54,54 @@
         "type": "github"
       }
     },
-    "hercules-ci-effects": {
+    "flake-utils_2": {
+      "locked": {
+        "lastModified": 1667077288,
+        "narHash": "sha256-bdC8sFNDpT0HK74u9fUkpbf1MEzVYJ+ka7NXCdgBoaA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "6ee9ebb6b1ee695d2cacc4faa053a7b9baa76817",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "hercules-ci-agent": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "flake-parts": "flake-parts_2",
+        "nix-darwin": "nix-darwin",
+        "nixpkgs": "nixpkgs",
+        "pre-commit-hooks-nix": "pre-commit-hooks-nix"
       },
       "locked": {
-        "lastModified": 1653841712,
-        "narHash": "sha256-XBF4i1MuIRAEbFpj3Z3fVaYxzNEsYapyENtw3vG+q1I=",
+        "lastModified": 1668032598,
+        "narHash": "sha256-KJF0ULd33lLOQVO26Ea1NKObSi9DIUfaxXducaKKpec=",
+        "owner": "hercules-ci",
+        "repo": "hercules-ci-agent",
+        "rev": "58954ab190bbc27a9d5149ebdafbf80851476461",
+        "type": "github"
+      },
+      "original": {
+        "id": "hercules-ci-agent",
+        "ref": "on-schedule",
+        "type": "indirect"
+      }
+    },
+    "hercules-ci-effects": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "hercules-ci-agent": "hercules-ci-agent",
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1668147980,
+        "narHash": "sha256-dHu5VIGQvZoHtqr5tmndpiVVk5JnJ/6wZUNRwEfvIxk=",
         "owner": "hercules-ci",
         "repo": "hercules-ci-effects",
-        "rev": "e14d2131b7c81acca3904b584ac45fb72da64dd2",
+        "rev": "244595b8dcfea8c6ac52a99157653162d26ea6d3",
         "type": "github"
       },
       "original": {
@@ -33,13 +110,35 @@
         "type": "github"
       }
     },
+    "nix-darwin": {
+      "inputs": {
+        "nixpkgs": [
+          "hercules-ci-effects",
+          "hercules-ci-agent",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1657835815,
+        "narHash": "sha256-CnZszAYpNKydh6N7+xg+eRtWNVoAAGqc6bg+Lpgq1xc=",
+        "owner": "LnL7",
+        "repo": "nix-darwin",
+        "rev": "54a24f042f93c79f5679f133faddedec61955cf2",
+        "type": "github"
+      },
+      "original": {
+        "owner": "LnL7",
+        "repo": "nix-darwin",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1647297614,
-        "narHash": "sha256-ulGq3W5XsrBMU/u5k9d4oPy65pQTkunR4HKKtTq0RwY=",
+        "lastModified": 1660305968,
+        "narHash": "sha256-r0X1pZCSEA6mzt5OuTA7nHuLmvnbkwgpFAh1iLIx4GU=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "73ad5f9e147c0d2a2061f1d4bd91e05078dc0b58",
+        "rev": "c4a0efdd5a728e20791b8d8d2f26f90ac228ee8d",
         "type": "github"
       },
       "original": {
@@ -49,18 +148,51 @@
         "type": "github"
       }
     },
+    "nixpkgs-lib": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1665349835,
+        "narHash": "sha256-UK4urM3iN80UXQ7EaOappDzcisYIuEURFRoGQ/yPkug=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "34c5293a71ffdb2fe054eb5288adc1882c1eb0b1",
+        "type": "github"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1653476104,
-        "narHash": "sha256-oVuWUnGQX+fRn/cFoNfbLEUGtsyyXuMLDQFEZ2OxP3k=",
+        "lastModified": 1664384182,
+        "narHash": "sha256-RM7C+6c9oSeZuoCCXOCRZUI1o4wpLo6pmOz1PxMN1ig=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "52392d42c156db5b889db7f3cc3e9909e4259b2a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
+      "locked": {
+        "lastModified": 1668145650,
+        "narHash": "sha256-RJsYVz7j6HhXQtcFQJz9bZsgwFG8MblmOt8A4iD1AlY=",
         "owner": "hercules-ci",
         "repo": "nixpkgs",
-        "rev": "612e22e67eb6f8d5bfb6288abe515e9da3b96103",
+        "rev": "b106ff14ede4034f8771025f8ac785144358f3cd",
         "type": "github"
       },
       "original": {
         "owner": "hercules-ci",
-        "ref": "module-docs-update",
+        "ref": "options-markdown-and-errors",
         "repo": "nixpkgs",
         "type": "github"
       }
@@ -69,6 +201,8 @@
       "inputs": {
         "flake-utils": "flake-utils",
         "nixpkgs": [
+          "hercules-ci-effects",
+          "hercules-ci-agent",
           "nixpkgs"
         ]
       },
@@ -87,11 +221,32 @@
         "type": "github"
       }
     },
+    "pre-commit-hooks-nix_2": {
+      "inputs": {
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1667992213,
+        "narHash": "sha256-8Ens8ozllvlaFMCZBxg6S7oUyynYx2v7yleC5M0jJsE=",
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "rev": "ebcbfe09d2bd6d15f68de3a0ebb1e4dcb5cd324b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "hercules-ci-effects": "hercules-ci-effects",
-        "nixpkgs": "nixpkgs_2",
-        "pre-commit-hooks-nix": "pre-commit-hooks-nix"
+        "nixpkgs": "nixpkgs_3",
+        "pre-commit-hooks-nix": "pre-commit-hooks-nix_2"
       }
     }
   },
diff --git a/dev/flake.nix b/dev/flake.nix
index 1b1d4e1..3344f42 100644
--- a/dev/flake.nix
+++ b/dev/flake.nix
@@ -3,13 +3,12 @@
 
   inputs = {
     # Flakes don't give us a good way to depend on .., so we don't.
-    # This has drastic consequences of course.
+    # As a consequence, this flake is a little non-standard, and
+    # we can't use the `nix` CLI as expected.
 
-    # https://github.com/NixOS/nixpkgs/pull/174460
-    # https://github.com/NixOS/nixpkgs/pull/174470
-    nixpkgs.url = "github:hercules-ci/nixpkgs/module-docs-update";
+    nixpkgs.url = "github:hercules-ci/nixpkgs/options-markdown-and-errors";
 
-    pre-commit-hooks-nix.url = "github:hercules-ci/pre-commit-hooks.nix/flakeModule";
+    pre-commit-hooks-nix.url = "github:cachix/pre-commit-hooks.nix";
     pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
 
     hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";
@@ -17,7 +16,7 @@
 
   outputs = { self, ... }:
     {
-      # Without good or dev outputs, we only use flakes for inputs here.
       # The dev tooling is in ./flake-module.nix
+      # See comment at `inputs` above.
     };
 }
diff --git a/lib.nix b/lib.nix
index 2d38daa..a57d687 100644
--- a/lib.nix
+++ b/lib.nix
@@ -109,7 +109,7 @@ let
           ${name} = mkOption {
             type = types.lazyAttrsOf option.type;
             default = { };
-            description = lib.mdDoc ''
+            description = ''
               See {option}`perSystem.${name}` for description and examples.
             '';
           };
diff --git a/modules/apps.nix b/modules/apps.nix
index a3f8219..dcd5b09 100644
--- a/modules/apps.nix
+++ b/modules/apps.nix
@@ -28,13 +28,13 @@ let
         type = lib.types.enum [ "app" ];
         default = "app";
         description = ''
-          A type tag for <literal>apps</literal> consumers.
+          A type tag for `apps` consumers.
         '';
       };
       program = mkOption {
         type = programType;
         description = ''
-          A path to an executable or a derivation with <literal>meta.mainProgram</literal>.
+          A path to an executable or a derivation with `meta.mainProgram`.
         '';
       };
     };
@@ -46,7 +46,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf appType;
     default = { };
     description = ''
-      Programs runnable with nix run <literal>.#&lt;name></literal>.
+      Programs runnable with nix run `<name>`.
     '';
     example = lib.literalExpression or lib.literalExample ''
       {
diff --git a/modules/checks.nix b/modules/checks.nix
index 12dde09..d849c65 100644
--- a/modules/checks.nix
+++ b/modules/checks.nix
@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      Derivations to be built by nix flake check.
+      Derivations to be built by [`nix flake check`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake-check.html).
     '';
   };
   file = ./checks.nix;
diff --git a/modules/darwinModules.nix b/modules/darwinModules.nix
index 0e3b017..2e39a00 100644
--- a/modules/darwinModules.nix
+++ b/modules/darwinModules.nix
@@ -19,7 +19,7 @@ in
         default = { };
         apply = mapAttrs (k: v: { _file = "${toString self.outPath}/flake.nix#darwinModules.${k}"; imports = [ v ]; });
         description = ''
-          Nix-darwin modules.
+          [nix-darwin](https://daiderd.com/nix-darwin/) modules.
         '';
       };
     };
diff --git a/modules/devShells.nix b/modules/devShells.nix
index 7ebbeb6..6521fa8 100644
--- a/modules/devShells.nix
+++ b/modules/devShells.nix
@@ -14,8 +14,8 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      An attribute set of packages to be built by <literal>nix develop .#&lt;name></literal>.
-      <literal>nix build .#&lt;name></literal> will run <literal>devShells.&lt;name></literal>.
+      An attribute set of packages to be used as shells.
+      [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
     '';
   };
   file = ./devShells.nix;
diff --git a/modules/flake.nix b/modules/flake.nix
index 3b8ed92..884b2de 100644
--- a/modules/flake.nix
+++ b/modules/flake.nix
@@ -17,7 +17,7 @@ in
         ];
       };
       description = ''
-        Raw flake attributes. Any attribute can be set here, but some
+        Raw flake output attributes. Any attribute can be set here, but some
         attributes are represented by options, to provide appropriate
         configuration merging.
       '';
diff --git a/modules/formatter.nix b/modules/formatter.nix
index d5b0435..b6098db 100644
--- a/modules/formatter.nix
+++ b/modules/formatter.nix
@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.nullOr types.package;
     default = null;
     description = ''
-      A package used by <literal>nix fmt</literal>.
+      A package used by [`nix fmt`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-fmt.html).
     '';
   };
   file = ./formatter.nix;
diff --git a/modules/legacyPackages.nix b/modules/legacyPackages.nix
index f07ab16..36df4dd 100644
--- a/modules/legacyPackages.nix
+++ b/modules/legacyPackages.nix
@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.raw;
     default = { };
     description = ''
-      An attribute set of unmergeable values. This is also used by <literal>nix build .#&lt;attrpath></literal>.
+      An attribute set of unmergeable values. This is also used by [`nix build .#<attrpath>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
     '';
   };
   file = ./legacyPackages.nix;
diff --git a/modules/nixosConfigurations.nix b/modules/nixosConfigurations.nix
index f62e4b4..7ddffd2 100644
--- a/modules/nixosConfigurations.nix
+++ b/modules/nixosConfigurations.nix
@@ -16,7 +16,7 @@ in
         type = types.lazyAttrsOf types.raw;
         default = { };
         description = ''
-          Instantiated NixOS configurations.
+          Instantiated NixOS configurations. Used by `nixos-rebuild`.
         '';
         example = literalExpression ''
           {
@@ -24,6 +24,7 @@ in
               system = "x86_64-linux";
               modules = [
                 ./my-machine/nixos-configuration.nix
+                config.nixosModules.my-module
               ];
             };
           }
diff --git a/modules/nixosModules.nix b/modules/nixosModules.nix
index bbd1afd..1d21f9e 100644
--- a/modules/nixosModules.nix
+++ b/modules/nixosModules.nix
@@ -20,6 +20,8 @@ in
         apply = mapAttrs (k: v: { _file = "${toString self.outPath}/flake.nix#nixosModules.${k}"; imports = [ v ]; });
         description = ''
           NixOS modules.
+
+          You may use this for reusable pieces of configuration, service modules, etc.
         '';
       };
     };
diff --git a/modules/overlays.nix b/modules/overlays.nix
index 9363c82..86fc457 100644
--- a/modules/overlays.nix
+++ b/modules/overlays.nix
@@ -24,12 +24,12 @@ in
           }
         '';
         description = ''
-          An attribute set of overlays.
+          An attribute set of [overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).
 
           Note that the overlays themselves are not mergeable. While overlays
           can be composed, the order of composition is significant, but the
           module system does not guarantee sufficiently deterministic
-          definition ordering, across versions and when changing <literal>imports</literal>.
+          definition ordering, across versions and when changing `imports`.
         '';
       };
     };
diff --git a/modules/packages.nix b/modules/packages.nix
index a6a22c5..dcb29eb 100644
--- a/modules/packages.nix
+++ b/modules/packages.nix
@@ -14,8 +14,9 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      An attribute set of packages to be built by <literal>nix build .#&lt;name></literal>.
-      <literal>nix build .#&lt;name></literal> will build <literal>packages.&lt;name></literal>.
+      An attribute set of packages to be built by [`nix build`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
+
+      `nix build .#<name>` will build `packages.<name>`.
     '';
   };
   file = ./packages.nix;
diff --git a/modules/perSystem.nix b/modules/perSystem.nix
index 1e9be2c..9c5f62d 100644
--- a/modules/perSystem.nix
+++ b/modules/perSystem.nix
@@ -16,17 +16,21 @@ in
 {
   options = {
     systems = mkOption {
-      description = "All the system types to enumerate in the flake.";
+      description = ''
+        All the system types to enumerate in the flake output subattributes.
+
+        In other words, all valid values for `system` in e.g. `packages.<system>.foo`.
+      '';
       type = types.listOf types.str;
     };
 
     perInput = mkOption {
-      description = "Function from system to function from flake to <literal>system</literal>-specific attributes.";
+      description = "Function from system to function from flake to `system`-specific attributes.";
       type = types.functionTo (types.functionTo (types.lazyAttrsOf types.unspecified));
     };
 
     perSystem = mkOption {
-      description = "A function from system to flake-like attributes omitting the <literal>&lt;system></literal> attribute.";
+      description = "A function from system to flake-like attributes omitting the `<system>` attribute.";
       type = mkPerSystemType ({ config, system, ... }: {
         _file = ./perSystem.nix;
         config = {
diff --git a/modules/transposition.nix b/modules/transposition.nix
index aec1563..5ddfcd0 100644
--- a/modules/transposition.nix
+++ b/modules/transposition.nix
@@ -18,11 +18,11 @@ let
         type = types.bool;
         default = false;
         description = ''
-          Whether to provide a stub option declaration for <option>perSystem.&lt;name></option>
+          Whether to provide a stub option declaration for {option}`perSystem.<name>`.
 
           The stub option declaration does not support merging and lacks
-          documentation, so you are recommended to declare the <option>perSystem.&lt;name></option>
-          option yourself and avoid <option>adHoc</option>.
+          documentation, so you are recommended to declare the {option}`perSystem.<name>`
+          option yourself and avoid {option}`adHoc`.
         '';
       };
     };
@@ -38,12 +38,12 @@ in
         Transposition is the operation that swaps the indices of a data structure.
         Here it refers specifically to the transposition between
 
-        <literal>
-          perSystem: .''${system}.''${attribute}
-          outputs:   .''${attribute}.''${system}
-        </literal>
+        ```plain
+        perSystem: .''${system}.''${attribute}
+        outputs:   .''${attribute}.''${system}
+        ```
 
-        It also defines the reverse operation in <option>perInput</option>.
+        It also defines the reverse operation in [{option}`perInput`](#opt-perInput).
       '';
       type =
         types.lazyAttrsOf
diff --git a/site/flake-module.nix b/site/flake-module.nix
index 38312f0..617ccd8 100644
--- a/site/flake-module.nix
+++ b/site/flake-module.nix
@@ -16,15 +16,16 @@
         let sourcePathStr = toString sourcePath;
         in
         opt:
-        let declarations = concatMap
-          (decl:
-            if hasPrefix sourcePathStr (toString decl)
-            then
-              let subpath = removePrefix sourcePathStr (toString decl);
-              in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
-            else [ ]
-          )
-          opt.declarations;
+        let
+          declarations = concatMap
+            (decl:
+              if hasPrefix sourcePathStr (toString decl)
+              then
+                let subpath = removePrefix sourcePathStr (toString decl);
+                in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
+              else [ ]
+            )
+            opt.declarations;
         in
         if declarations == [ ]
         then opt // { visible = false; }
@@ -39,6 +40,8 @@
             transformOptions = filterTransformOptions {
               inherit sourceName baseUrl sourcePath;
             };
+            warningsAreErrors = true; # not sure if feasible long term
+            markdownByDefault = true;
           }).optionsDocBook;
           inherit title;
         } ''