docs: split swarm/deploy options into their own reference pages

services.hyperhive.swarm.* used to carry both swarm-wide facts (name,
domain, hives, ca) and the 'does THIS host run it' toggles for every
swarm service. deploy.nix already split those toggles out into their
own services.hyperhive.deploy.* namespace; this is the docs-side
follow-up now that swarm.* is genuinely swarm-wide-only.

nix/docs/default.nix: host.md drops the swarm/deploy subtrees
(builtins.removeAttrs on the already-picked host tree, not
lib.recursiveUpdate -- that merges rather than deletes, which would
have silently kept them on host.md); swarm.md and deploy.md are new
markdown pages, each its own pickSubtrees root. nix/packages/default.nix
exposes docs-swarm/docs-deploy as flake outputs alongside the existing
docs-host/docs-agent. docs/gotchas.md's Nix options reference section
and docs/swarm/README.md get pointers to the new split.

nix/docs/default.nix

@@ -5,11 +5,21 @@
   nixosSystem,
 }:
 # Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
-# module trees, emitted as CommonMark (`host.md` + `agent.md`). The
-# HTML + CSS for `/options/` is rendered downstream by the website
-# repo, which owns the presentation and shares one stylesheet with the
-# prose `/docs/` tree. Full pipeline + subtree-pick / output-tree
-# rationale: docs/gotchas.md::Nix options reference.
+# module trees, emitted as CommonMark (`host.md` + `agent.md` +
+# `swarm.md` + `deploy.md`). The HTML + CSS for `/options/` is rendered
+# downstream by the website repo, which owns the presentation and
+# shares one stylesheet with the prose `/docs/` tree. Full pipeline +
+# subtree-pick / output-tree rationale: docs/gotchas.md::Nix options
+# reference.
+#
+# `swarm.md`/`deploy.md` split off `host.md` (mara: "move swarm options
+# to new docs page... deploy.* is also one of the things that should be
+# a sub page"): `services.hyperhive.swarm.*` was mixed — swarm-wide
+# facts (name, domain, hives, ca) alongside "does THIS host run it"
+# toggles — until `deploy.nix` moved every such toggle to its own flat
+# `services.hyperhive.deploy.*` namespace. That reorg landed first
+# (see deploy.nix's file-top comment); this is the docs-side follow-up
+# now that `swarm.*` genuinely is swarm-wide-only.
 let
   # Content-addressed narrow source covering only the nix/ directory.
   # `builtins.unsafeDiscardStringContext` strips `self`'s store-path
@@ -105,13 +115,44 @@ let
     in
     lib.foldl' lib.recursiveUpdate { } (map pick roots);
 
-  hostOptions = pickSubtrees hostEval.options [
+  hostOptionsFull = pickSubtrees hostEval.options [
     [
       "services"
       "hyperhive"
     ]
   ];
 
+  # `swarm.*` and `deploy.*` get their own pages below — drop them from
+  # the host tree rather than duplicating them here too. `pickSubtrees`
+  # only ever picked `services.hyperhive` for `hostOptionsFull` (nothing
+  # else lives under `services` in this tree), so a direct replacement
+  # is correct here — NOT `lib.recursiveUpdate`, which merges rather
+  # than deletes: a key present on the left and absent on the right
+  # survives the "update," which would silently keep `swarm`/`deploy`
+  # on `host.md` instead of dropping them.
+  hostOptions = {
+    services.hyperhive = builtins.removeAttrs hostOptionsFull.services.hyperhive [
+      "swarm"
+      "deploy"
+    ];
+  };
+
+  swarmOptions = pickSubtrees hostEval.options [
+    [
+      "services"
+      "hyperhive"
+      "swarm"
+    ]
+  ];
+
+  deployOptions = pickSubtrees hostEval.options [
+    [
+      "services"
+      "hyperhive"
+      "deploy"
+    ]
+  ];
+
   agentOptions = pickSubtrees agentEval.options [
     [ "hyperhive" ]
   ];
@@ -121,6 +162,16 @@ let
     inherit transformOptions;
   };
 
+  swarmDoc = pkgs.nixosOptionsDoc {
+    options = swarmOptions;
+    inherit transformOptions;
+  };
+
+  deployDoc = pkgs.nixosOptionsDoc {
+    options = deployOptions;
+    inherit transformOptions;
+  };
+
   agentDoc = pkgs.nixosOptionsDoc {
     options = agentOptions;
     inherit transformOptions;
@@ -144,32 +195,43 @@ let
       } > $out
     '';
 
-  # Bundle landing page — a short markdown index pointing at the two
+  # Bundle landing page — a short markdown index pointing at the four
   # reference pages.
   indexMD = pkgs.writeText "hyperhive-options-index.md" ''
     # hyperhive — nix options reference
 
-    Auto-generated from the hyperhive flake. Two reading paths:
+    Auto-generated from the hyperhive flake. Four reading paths:
 
     - [host options](host.md) — options exposed by
       `hyperhive.nixosModules.default` to operator host configurations
-      (`services.hyperhive.{enable,domain,c0re,gateway}.*`,
-      `services.hyperhive.swarm.{forge,matrix}.*`).
+      (`services.hyperhive.{enable,domain,c0re,gateway,tls,network}.*`).
+    - [swarm options](swarm.md) — swarm-wide facts, identical on every
+      host in the swarm (`services.hyperhive.swarm.{name,domain,hives,
+      ca,forge,matrix}.*`).
+    - [deploy options](deploy.md) — this host's own deployment
+      decisions, necessarily different per host
+      (`services.hyperhive.deploy.*` — does *this* machine run
+      grafana, the swarm controller, authelia, …).
     - [per-agent options](agent.md) — options declared in
       `nix/agent-modules/`, visible from every `agent.nix`
       (`hyperhive.model`, `hyperhive.allowedRecipients`,
       `hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
       `hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).
 
-    Regenerate with `nix build .#docs` (bundle), `.#docs-host`, or
-    `.#docs-agent`. Consumed by the website repo to render `/options/`.
+    Regenerate with `nix build .#docs` (bundle), `.#docs-host`,
+    `.#docs-swarm`, `.#docs-deploy`, or `.#docs-agent`. Consumed by the
+    website repo to render `/options/`.
   '';
 
   hostMD = mkMarkdownPage "docs-host" "hyperhive — host options" hostDoc;
+  swarmMD = mkMarkdownPage "docs-swarm" "hyperhive — swarm options" swarmDoc;
+  deployMD = mkMarkdownPage "docs-deploy" "hyperhive — deploy options" deployDoc;
   agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
 in
 {
   host = hostMD;
+  swarm = swarmMD;
+  deploy = deployMD;
   agent = agentMD;
 
   # Bundle of the option reference as markdown. The website renders
@@ -179,6 +241,8 @@ in
     mkdir -p $out
     cp ${indexMD} $out/index.md
     cp ${hostMD} $out/host.md
+    cp ${swarmMD} $out/swarm.md
+    cp ${deployMD} $out/deploy.md
     cp ${agentMD} $out/agent.md
   '';
 }