From c490c72413a25e21f4e794b9161630ff1629a709 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Fri, 6 Nov 2026 20:14:23 +0100
Subject: [PATCH] docs: per-agent options page picks services.hyperhive.agent,
 and fails the eval if it goes empty

the page picked the top-level hyperhive attr, which stopped existing when the
agent namespace moved under services.hyperhive.agent, so it rendered no
options. the pick now uses the new root and asserts model, user.privateUsers
and nixBuilds are present. the acp preset submodule options get the
descriptions the now-rendered page requires.

Closes #6136
---
 nix/agent-modules/agent-service.nix |  7 ++++++-
 nix/docs/default.nix                | 29 +++++++++++++++++++++++++++--
 2 files changed, 33 insertions(+), 3 deletions(-)

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;