diff --git a/docs/conventions.md b/docs/conventions.md
index 894b6f48..a390dbbd 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -297,7 +297,7 @@ status_text, status_set_at, hive_name, swarm_name }`:
   or when `running = false` (see above).
 - `hive_name` / `swarm_name`: display names read from
   `HYPERHIVE_HIVE_NAME` / `HYPERHIVE_SWARM_NAME` env (sourced from
-  `services.hyperhive.hiveName` / `services.hyperhive.swarmName`).
+  `services.hyperhive.hiveName` / `services.hyperhive.swarm.name`).
   Both `None` when the options aren't configured.
 
 ### Timestamps on the wire
diff --git a/docs/observability.md b/docs/observability.md
index 97993735..28350376 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -121,7 +121,7 @@ Every agent's export includes these resource attributes automatically:
 | `service.name` | `hyperhive-agent` (constant) |
 | `agent` | agent logical name (e.g. `iris`) |
 | `hive` | hive display name (`services.hyperhive.hiveName`) |
-| `swarm` | swarm display name (`services.hyperhive.swarmName`, if set) |
+| `swarm` | swarm display name (`services.hyperhive.swarm.name`, if set) |
 
 Additional labels can be appended via `extraResourceAttributes` (see option
 reference above); custom per-data-point labels can be passed with
diff --git a/docs/swarm.md b/docs/swarm.md
index 37eeba76..addf88f5 100644
--- a/docs/swarm.md
+++ b/docs/swarm.md
@@ -20,17 +20,19 @@ the additional config needed when the swarm spans multiple hosts.
 ```nix
 services.hyperhive = {
   domain   = "pr1ma.example.com";   # machine-addressable DNS domain
-  hiveName  = "pr1ma";              # human display name (optional)
-  swarmName = "constellat1on";      # shared swarm display name (optional)
+  hiveName = "pr1ma";               # human display name (optional)
+  swarm.name = "constellat1on";     # shared swarm display name (optional)
 };
 ```
 
 `domain` is required when matrix federation is on (`matrix.enable`);
 it drives `HYPERHIVE_HIVE_DOMAIN` in every container so agents can
 form qualified labels (`iris@pr1ma.example.com`). `hiveName` and
-`swarmName` are purely display — they surface in the dashboard chrome
+`swarm.name` are purely display — they surface in the dashboard chrome
 header and per-agent system prompts. Federated hives at different
-domains can share a `swarmName`.
+domains can share a `swarm.name`; that it sits under `swarm` and
+`hiveName` does not is the whole distinction — one names this hive, the
+other names the group it belongs to.
 
 See `docs/conventions.md` § Hive identity for the env-var chain
 and `qualify()` / `qualified_label()` semantics.
diff --git a/hive-agent-mcp/src/mcp/mod.rs b/hive-agent-mcp/src/mcp/mod.rs
index 83a4bec3..354aa5d2 100644
--- a/hive-agent-mcp/src/mcp/mod.rs
+++ b/hive-agent-mcp/src/mcp/mod.rs
@@ -437,8 +437,9 @@ impl AgentServer {
         `status_set_at` are stale pre-stop values and should not be treated as live), \
         and the target's self-reported `status` text (set via `set_status`) plus how \
         long ago it was set. Also returns the hive + swarm display names (`hive_name`, \
-        `swarm_name`) when the operator has configured `services.hyperhive.{hiveName, \
-        swarmName}`; both lines omitted when unset. Pass `name` to query a peer (e.g. \
+        `swarm_name`) when the operator has configured \
+        `services.hyperhive.hiveName` / `services.hyperhive.swarm.name`; both lines \
+        omitted when unset. Pass `name` to query a peer (e.g. \
         check whether iris is idle before pinging them); omit `name` to get your own \
         identity stamp — handy for state files / commit messages / cross-agent \
         attribution that won't drift across renames or session-continue boundaries \
diff --git a/hive-agent/src/identity.rs b/hive-agent/src/identity.rs
index a136ad48..85c36619 100644
--- a/hive-agent/src/identity.rs
+++ b/hive-agent/src/identity.rs
@@ -42,7 +42,7 @@ pub fn hive_name() -> Option<String> {
 /// Human display name of the wider swarm this hive belongs to (e.g.
 /// `constellat1on`). Federated hives at different DNS domains can
 /// share a swarm name. Returns None when the host-side
-/// `services.hyperhive.swarmName` option is unset.
+/// `services.hyperhive.swarm.name` option is unset.
 #[must_use]
 pub fn swarm_name() -> Option<String> {
     non_empty_env("HYPERHIVE_SWARM_NAME")
diff --git a/hive-c0re/src/container_view.rs b/hive-c0re/src/container_view.rs
index 29fbe451..2c52e624 100644
--- a/hive-c0re/src/container_view.rs
+++ b/hive-c0re/src/container_view.rs
@@ -268,7 +268,9 @@ fn read_active_model(name: &hive_types::Ident) -> Option<String> {
 
 /// Host-side hive + swarm display names, read from the c0re service's
 /// own process env. The `hive-c0re.nix` module sets these from
-/// `services.hyperhive.{hiveName, swarmName}`. The agent-side
+/// `services.hyperhive.hiveName` + `services.hyperhive.swarm.name`
+/// (the hive names itself; the swarm it joins is named one level out).
+/// The agent-side
 /// `hive-agent::identity::{hive_name, swarm_name}` accessors read the
 /// same env vars after they're forwarded into each sub-agent's
 /// harness service environment by `meta::render_flake`; surfacing
diff --git a/hive-c0re/src/dashboard/state_snapshot.rs b/hive-c0re/src/dashboard/state_snapshot.rs
index df3f486b..66edacbf 100644
--- a/hive-c0re/src/dashboard/state_snapshot.rs
+++ b/hive-c0re/src/dashboard/state_snapshot.rs
@@ -117,7 +117,7 @@ pub(super) struct StateSnapshot {
     hive_name: Option<String>,
     /// Human name of the wider swarm this hive belongs to (e.g.
     /// `"constellat1on"`). Sourced from `HYPERHIVE_SWARM_NAME` env
-    /// var, set from `services.hyperhive.swarmName`. `None` when
+    /// var, set from `services.hyperhive.swarm.name`. `None` when
     /// unset — chrome omits the swarm segment of the breadcrumb.
     swarm_name: Option<String>,
     /// Peer hives in the same swarm. Parsed from `HYPERHIVE_PEERS`
diff --git a/nix/agent-modules/claude-settings.nix b/nix/agent-modules/claude-settings.nix
index 5070e8e5..26b96ffb 100644
--- a/nix/agent-modules/claude-settings.nix
+++ b/nix/agent-modules/claude-settings.nix
@@ -243,7 +243,7 @@ in
     description = ''
       Human-readable swarm name, rendered per-agent by
       `meta.rs::render_flake` from the host's
-      `services.hyperhive.swarmName`. Same build-time/runtime split as
+      `services.hyperhive.swarm.name`. Same build-time/runtime split as
       `hyperhive.hiveName`.
 
       `null` means the hive is not part of a named swarm.