diff --git a/nix/agent-modules/agent-service.nix b/nix/agent-modules/agent-service.nix
index 00a32f7e..c7c89b8b 100644
--- a/nix/agent-modules/agent-service.nix
+++ b/nix/agent-modules/agent-service.nix
@@ -296,14 +296,19 @@ in
       type = lib.types.attrsOf (
         lib.types.submodule {
           options = {
-            command = lib.mkOption { type = lib.types.str; };
+            command = lib.mkOption {
+              type = lib.types.str;
+              description = "Executable that speaks ACP over stdio.";
+            };
             args = lib.mkOption {
               type = lib.types.listOf lib.types.str;
               default = [ ];
+              description = "Arguments passed to `command`.";
             };
             env = lib.mkOption {
               type = lib.types.attrsOf lib.types.str;
               default = { };
+              description = "Environment for this preset only, rendered into the nix store.";
             };
           };
         }
diff --git a/nix/docs/default.nix b/nix/docs/default.nix
index 0b5d99fd..ae002cca 100644
--- a/nix/docs/default.nix
+++ b/nix/docs/default.nix
@@ -151,9 +151,34 @@ let
     ]
   ];
 
-  agentOptions = pickSubtrees agentEval.options [
-    [ "hyperhive" ]
+  # Options live under `services.hyperhive.agent`. The page must keep
+  # listing known options from different agent modules; an empty page
+  # fails the eval instead of publishing.
+  agentRoot = [
+    "services"
+    "hyperhive"
+    "agent"
   ];
+  agentRequired = [
+    (agentRoot ++ [ "model" ])
+    (
+      agentRoot
+      ++ [
+        "user"
+        "privateUsers"
+      ]
+    )
+    (agentRoot ++ [ "nixBuilds" ])
+  ];
+  agentPicked = pickSubtrees agentEval.options [ agentRoot ];
+  agentOptions =
+    assert lib.assertMsg (lib.all (p: lib.hasAttrByPath p agentPicked) agentRequired)
+      "per-agent options page lost required options: ${
+        lib.concatMapStringsSep ", " (lib.concatStringsSep ".") (
+          lib.filter (p: !lib.hasAttrByPath p agentPicked) agentRequired
+        )
+      }";
+    agentPicked;
 
   hostDoc = pkgs.nixosOptionsDoc {
     options = hostOptions;