diff --git a/docs/gotchas.md b/docs/gotchas.md
index 22351306..693e1844 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -452,13 +452,20 @@ hyperhive subsystem `mkForce false` so heavy build inputs stay out of
 the eval) and `agentEval` (evaluates `agent.nix` fresh for the
 per-agent options tree).
 
-Three output trees consumed by `flake.nix`, all **markdown**:
+Five output trees consumed by `flake.nix`, all **markdown**:
 
 - `docs-host` — operator-facing host module options
-  (`services.hyperhive.*`)
+  (`services.hyperhive.*` minus the `swarm`/`deploy` subtrees below)
+- `docs-swarm` — swarm-wide facts, identical on every host in the swarm
+  (`services.hyperhive.swarm.*`)
+- `docs-deploy` — this host's own deployment decisions, necessarily
+  different per host (`services.hyperhive.deploy.*` — added by
+  `nix/host-modules/deploy.nix`, split out of `swarm.*` for exactly this
+  reason: see that file's own comment)
 - `docs-agent` — per-agent harness options (`hyperhive.*`
   declared in `nix/agent-modules/`)
-- `docs` — bundle of `index.md` + `host.md` + `agent.md`
+- `docs` — bundle of `index.md` + `host.md` + `swarm.md` +
+  `deploy.md` + `agent.md`
 
 Pipeline:
 
@@ -478,7 +485,11 @@ Host options live entirely under `services.hyperhive.*`. The
 `pickSubtrees` filter is rooted at `["services" "hyperhive"]` so the
 options tree picks up everything under that root — picking against
 stray roots produces an empty tree and renders the host page as
-template chrome with no `<h2>` headers.
+template chrome with no `<h2>` headers. `docs-host` then drops the
+`swarm`/`deploy` subtrees from that picked tree (`removeAttrs`, not a
+second `pickSubtrees` root — the one exclusion this file needs doesn't
+earn a general-purpose helper) since `docs-swarm`/`docs-deploy` each
+pick their own root instead.
 
 #### Docs drv stability: `nixSrc`
 
diff --git a/docs/swarm/README.md b/docs/swarm/README.md
index 3ca5c4c4..743568ed 100644
--- a/docs/swarm/README.md
+++ b/docs/swarm/README.md
@@ -5,6 +5,13 @@ coordinate across one or more hives. A single hyperhive instance
 running on one host is already a swarm (one hive). This doc covers
 the additional config needed when the swarm spans multiple hosts.
 
+For the full option reference rather than prose: `services.hyperhive.swarm.*`
+(swarm-wide facts, identical on every host) and `services.hyperhive.deploy.*`
+(this host's own deployment decisions — does *this* machine run grafana,
+the swarm controller, authelia, …) are separate generated pages, `nix
+build .#docs-swarm` / `.#docs-deploy` or the website's `/options/swarm.html`
+/ `/options/deploy.html`.
+
 ## Terminology
 
 - **hive** — a single hyperhive installation on one host. Has its
diff --git a/nix/docs/default.nix b/nix/docs/default.nix
index 5b4b7f95..ec1836df 100644
--- a/nix/docs/default.nix
+++ b/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
   '';
 }
diff --git a/nix/packages/default.nix b/nix/packages/default.nix
index 4b3b6668..90487908 100644
--- a/nix/packages/default.nix
+++ b/nix/packages/default.nix
@@ -259,11 +259,13 @@ in
   ruth-toplevel = self.nixosConfigurations.ruth.config.system.build.toplevel;
 
   # Auto-generated nix options reference for hyperhive.
-  # `docs` bundles host + agent pages into one tree; the split
-  # outputs are useful when consumers only want one surface.
-  # All three are pure markdown — no rust or frontend deps in
+  # `docs` bundles host + swarm + deploy + agent pages into one tree;
+  # the split outputs are useful when consumers only want one surface.
+  # All five are pure markdown — no rust or frontend deps in
   # the closure, so `nix build .#docs` is cheap.
   docs = docsAttrs.bundle;
   docs-host = docsAttrs.host;
+  docs-swarm = docsAttrs.swarm;
+  docs-deploy = docsAttrs.deploy;
   docs-agent = docsAttrs.agent;
 }