drop option renames and removals older than two weeks

Refs #5379

claude-plugins/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "hyperhive",
-  "description": "hyperhive-authored Claude Code plugins, shipped hive-wide via the default hyperhive.claudeMarketplaces/claudePlugins nix options (nix/agent-modules/claude-settings.nix). Built as a nix store path and added with `claude plugin marketplace add <path>` - no forge repo or git remote needed. Add a new plugins/<name>/ subtree + one entry below to ship another.",
+  "description": "hyperhive-authored Claude Code plugins, shipped hive-wide via the default services.hyperhive.agent.claudeMarketplaces/claudePlugins nix options (nix/agent-modules/claude-settings.nix). Built as a nix store path and added with `claude plugin marketplace add <path>` - no forge repo or git remote needed. Add a new plugins/<name>/ subtree + one entry below to ship another.",
   "owner": {
     "name": "hyperhive"
   },

docs/swarm/ui.md

@@ -403,8 +403,8 @@ daemon's socket, so the host that runs the controller is the host that
 can serve the UI. A hive that merely _uses_ a swarm has nothing to serve.
 
 The UI build is `deploy.swarm-controller.ui.package` (defaulted from this
-flake's `swarm-ui` package). The older `deploy.swarm-ui.package` and
+flake's `swarm-ui` package). The older `deploy.swarm-ui.package` still works
-`swarm.ui.package` still work and warn at evaluation.
+and warns at evaluation.
 
 The UI answers on `services.hyperhive.swarm.domain` and nothing else. It
 shares that name with the swarm-controller it fronts — one service to a

frontend/packages/agent/build.mjs

@@ -17,7 +17,7 @@
 //                               resolved from @hive/shared)
 //
 // The in-container Rust binary mounts `dist/` (with per-agent
-// `hyperhive.frontend.extraFiles` layered on top) as a
+// `services.hyperhive.agent.frontend.extraFiles` layered on top) as a
 // `tower_http::ServeDir` fallback; the layout above keeps every URL
 // the HTML references reachable without rewriting paths.
 

frontend/packages/agent/package.json

@@ -2,7 +2,7 @@
   "name": "@hive/agent",
   "version": "0.0.0",
   "private": true,
-  "description": "hive-ag3nt per-container web UI. Bundled by esbuild into a static dist; served by the in-container Rust binary at runtime via tower_http::ServeDir. Per-agent additions are layered on top via the hyperhive.frontend.extraFiles nix option.",
+  "description": "hive-ag3nt per-container web UI. Bundled by esbuild into a static dist; served by the in-container Rust binary at runtime via tower_http::ServeDir. Per-agent additions are layered on top via the services.hyperhive.agent.frontend.extraFiles nix option.",
   "type": "module",
   "scripts": {
     "build": "node ./build.mjs",

frontend/packages/agent/src/components/Header.tsx

@@ -25,7 +25,7 @@
 import { useEffect, useRef } from "preact/hooks";
 import type { ComponentChildren } from "preact";
 
-// Icon 404s when the agent has no `hyperhive.icon` override (no
+// Icon 404s when the agent has no `services.hyperhive.agent.icon` override (no
 // bundled server-side default any more — see
 // `hive_agent::web_ui::screen::serve_icon`). Ports app.js's
 // `bindHeaderIconFallback` exactly: fire-and-forget load, swap to

frontend/packages/agent/src/components/MetaNav.tsx

@@ -2,7 +2,7 @@
 // (`@hive/shared/icons.js`'s `LinkIcon` — an emoji glyph can't match a
 // neighbouring icon's size/weight on any platform, see that file's
 // comment) in the pills cluster that opens a popover listing
-// stats/screen/forge/config + any `hyperhive.dashboardLinks` extras,
+// stats/screen/forge/config + any `services.hyperhive.agent.dashboardLinks` extras,
 // sourced from the backend's `agent_links()` (the single source of
 // truth — same list also feeds the dashboard card's icon strip) — plus
 // a `🧭 dashboard` back-link.

frontend/packages/agent/src/types.ts

@@ -38,7 +38,7 @@ export interface AgentState {
 
 // Mirrors `hive_agent::web_ui::state::AgentLink` — one meta-nav entry
 // in the agent page header (stats/screen/forge/config + any
-// `hyperhive.dashboardLinks` extras). `agent_links()` on the backend
+// `services.hyperhive.agent.dashboardLinks` extras). `agent_links()` on the backend
 // is the single source of truth for what links an agent exposes; see
 // docs/web-ui/agent.md::Header for the kind → URL resolution table.
 export interface AgentLink {

frontend/packages/dashboard/src/agents.js

@@ -663,7 +663,7 @@ export function renderContainers(s) {
   // `docs/web-ui/dashboard.md::Container row` + `docs/networking/gateway.md::Vhost map`.
   const gatewayLinks = !!(s && s.gateway_enabled);
   // Forge public URL: state.forge_public_url (set by the NixOS module
-  // from services.hyperhive.forge.publicUrl) or null — never guessed
+  // from services.hyperhive.swarm.forge.publicUrl) or null — never guessed
   // from "<hostname>:3000". `null` propagates down to
   // buildContainerLi/buildAgentMenu, which already hide forge links
   // rather than emit a possibly-wrong one.

frontend/packages/swarm-ui/src/pages/LinkMatrixAccountForm.tsx

@@ -149,7 +149,7 @@ export function LinkMatrixAccountForm({
           pattern={ACCOUNT_PATTERN}
           title="1-63 chars: letters, digits, underscore, hyphen"
           // Not "primary" — that reads as naming the hive-provided default
-          // account (`main`, reserved: see `hyperhive.matrixAccounts`'s own
+          // account (`main`, reserved: see `services.hyperhive.agent.matrixAccounts`'s own
           // module doc), which this route can neither create nor touch.
           // Picking a name with no relationship to that default avoids the
           // misread entirely, rather than requiring a reader to already know

hive-agent-mcp/README.md

@@ -24,7 +24,7 @@ or their own daemon instead of living here.
   in-agent socket the `hive-agent` harness serves.
 - **`client.rs`** — socket client to the hyperhive broker.
 - **`send_allow.rs`** — enforces the per-agent
-  `hyperhive.allowedRecipients` allow-list on `send`.
+  `services.hyperhive.agent.allowedRecipients` allow-list on `send`.
 - **`paths.rs`** — socket + state path resolution shared with the
   harness's own `paths.rs` conventions.
 

hive-agent/prompts/system.md

@@ -3,7 +3,7 @@ You are hyperhive agent `{label}` (qualified: `{qualified_label}`){hive_identity
 Tools (hyperhive surface). Full signature + behavior for each comes from the tool's own MCP description (you already received it via the MCP tool schema) — this is just the map of what exists and which ones are gated, so you know where to look:
 
 - **Inbox / messaging** (always available): `mcp__hyperhive__recv`, `mcp__hyperhive__ack_until`, `mcp__hyperhive__send`, `mcp__hyperhive__get_loose_ends`, `mcp__hyperhive__cancel_loose_end`, `mcp__hyperhive__mark_todos_done`, `mcp__hyperhive__remind`, `mcp__hyperhive__set_status`, `mcp__hyperhive__get_agent_meta`. `send` reaches peers on this hive only; **reach the operator over matrix** if you have the matrix MCP tools (`mcp__matrix__send_dm` or `mcp__matrix__send_message`); without them the operator reads your `set_status` line and turn output on the dashboard, and your logs. `send(to: "operator")` is refused. One habit worth internalizing beyond the tool descriptions themselves: prefer ending the turn over repeatedly polling `recv` when idle (only turn-boundaries observe in-container todo wakes — bash-task completions, matrix unread, forge activity — and ending the turn is also your checkpoint). For a large todo backlog (`get_loose_ends` caps at 40 rows), clear reviewed ids in bulk with `mark_todos_done` rather than cancelling one at a time — there's no blind range-clear, only ids you've actually looked at.
-- **Extra MCP tools** (some agents only): `mcp__<server>__<tool>` — agent-specific (matrix client, scraper, db connector, etc.) declared in your `agent.nix` under `hyperhive.extraMcpServers`. First-class tools, already operator-approved at deploy time.
+- **Extra MCP tools** (some agents only): `mcp__<server>__<tool>` — agent-specific (matrix client, scraper, db connector, etc.) declared in your `agent.nix` under `services.hyperhive.agent.extraMcpServers`. First-class tools, already operator-approved at deploy time.
 
 Need new packages, env vars, or other NixOS config for yourself? You can't edit your own config directly — open a PR on your `agent-configs/<name>` repo, or contact the operator directly. Config repos live at `/agents/{label}/config/` (read-only inside your container). All changes flow through operator-approved commits.
 

hive-agent/src/web_ui/state.rs

@@ -169,8 +169,8 @@ pub(super) struct StateSnapshot {
     links: Vec<AgentLink>,
     /// Public URL of the forge (e.g.
     /// `"https://forge.pr1ma.darkest.space"`). Sourced from
-    /// `HIVE_FORGE_PUBLIC_URL` (set from `services.hyperhive.forge.
+    /// `HIVE_FORGE_PUBLIC_URL` (set from
-    /// publicUrl`); `None` when unset. The frontend uses this to build
+    /// `services.hyperhive.swarm.forge.publicUrl`); `None` when unset. The frontend uses this to build
     /// forge nav-strip links, and **hides** the forge link entirely
     /// when absent rather than guessing `<hostname>:3000`.
     forge_public_url: Option<String>,

hive-screen-mcp/README.md

@@ -1,13 +1,13 @@
 # hive-screen-mcp
 
 A stdio MCP server that exposes screenshot, keyboard, and mouse tools to agents
-running a Weston Wayland compositor (`hyperhive.gui.enable = true`).
+running a Weston Wayland compositor (`services.hyperhive.agent.gui.enable = true`).
 
 ## When to use it
 
 This crate is the bridge for **GUI agents** — agents that drive graphical
 applications (browsers, desktop tools, game UIs) and need to see and interact
-with a Weston Wayland display. If your agent does not have `hyperhive.gui.enable
+with a Weston Wayland display. If your agent does not have `services.hyperhive.agent.gui.enable
 = true`, none of these tools will function.
 
 ## Tools
@@ -27,7 +27,7 @@ module; `HIVE_GUI_VNC_PORT` is set by the harness service (defaults to `5900`).
 ## Shape
 
 One binary (`hive-screen-mcp`) launched over stdio. The agent runtime wires it
-as an extra MCP server when `hyperhive.gui.enable = true`. There are no library
+as an extra MCP server when `services.hyperhive.agent.gui.enable = true`. There are no library
 exports — it is a self-contained binary crate.
 
 See the crate-root `//!` docs for the full per-tool implementation notes and

nix/agent-modules/default.nix

@@ -19,23 +19,6 @@
   ...
 }:
 let
-  # What an `agent.nix` still setting the dropped per-agent matrix switch is
-  # told. Shared by the two `mkRemovedOptionModule` entries below, one per
-  # spelling of the path.
-  matrixEnableRemoved = ''
-    The per-agent matrix switch is gone. Matrix is enabled for an agent exactly
-    when it has at least one services.hyperhive.agent.matrixAccounts entry, and
-    the hive-internal `main` entry is declared for you whenever
-    services.hyperhive.agent.matrix.url is non-null.
-
-    - `enable = true` was the default: drop the line, nothing else to do.
-    - `enable = false`: set services.hyperhive.agent.matrix.url = null instead
-      (and declare no accounts of your own). That is what leaves the account set
-      empty, which is now what suppresses the daemon, its path watcher and the
-      injected extraMcpServers.matrix entry.
-
-    See docs/tools/matrix.md.
-  '';
   hiveNameRemoved = ''
     An agent reads its hive's name at runtime from /etc/hyperhive-hive-facts,
     which the hive writes into every container, so no agent build sets it.
@@ -71,36 +54,12 @@ in
     ./packages.nix
     ./queue.nix
     ./queue-identity.nix
-    ./renamed-options.nix
     ./user.nix
     ./screen.nix
     ./weston-vnc.nix
-    (lib.mkRemovedOptionModule [ "hyperhive" "web" "useUnixSocket" ] ''
+    # The hive supplies both at runtime; a definition fails the eval, naming
-      Unix socket mode is always enabled for all agents. Remove the
+    # where the value comes from.
-      setting from your agent.nix.
-    '')
-    (lib.mkRemovedOptionModule [ "hyperhive" "allowedBashPatterns" ] ''
-      The built-in Bash tool is fully disabled; agents use
-      mcp__bash__run instead. Remove the setting from your agent.nix.
-    '')
-    # The dropped per-agent matrix switch. A removal, not a silent delete,
-    # because the definition that *changes meaning* is `false`: left undeclared
-    # it would be ignored and the agent would quietly gain the matrix tools its
-    # operator turned off. Failing the eval with the replacement spelling is the
-    # only outcome that cannot do that.
-    #
-    # Both spellings, for the same reason ../host-modules/deploy.nix lists both
-    # of `swarm|deploy.matrix.registrationTokenFile`: an existing agent.nix may
-    # carry either the `hyperhive.*` path or the `services.hyperhive.agent.*`
-    # one, and only the one it actually carries will fire. Neither is an entry
-    # in ./renamed-options.nix — a rename pointing at an undeclared option
-    # breaks evaluation for everyone, removed or not.
-    (lib.mkRemovedOptionModule [ "hyperhive" "matrix" "enable" ] matrixEnableRemoved)
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "agent" "matrix" "enable" ] matrixEnableRemoved)
-    # Both spellings, for the reason given above.
-    (lib.mkRemovedOptionModule [ "hyperhive" "hiveName" ] hiveNameRemoved)
     (lib.mkRemovedOptionModule [ "services" "hyperhive" "agent" "hiveName" ] hiveNameRemoved)
-    (lib.mkRemovedOptionModule [ "hyperhive" "claudeMemoryMaxBytes" ] memoryMaxBytesRemoved)
     (lib.mkRemovedOptionModule [
       "services"
       "hyperhive"

nix/agent-modules/renamed-options.nix

@@ -1,207 +0,0 @@
-# Deprecation shims for the agent tier's top-level `hyperhive.*` spelling.
-#
-# Per-agent options live at `services.hyperhive.agent.<name>`, beside the host
-# tier's `services.hyperhive.*`. These entries keep an `agent.nix` that still
-# uses the top-level `hyperhive.<name>` spelling evaluating, with a
-# deprecation warning.
-#
-# ⚠️ One entry per LEAF, not per namespace. A single entry for a parent path
-# only covers its children when the parent is a submodule-typed option; every
-# nested option here (`user`, `mcp`, `otel`, …) is a plain attrset of
-# declarations instead, so each leaf needs its own line — the same reason
-# `../host-modules/deploy.nix` renames the CI runner's knobs one by one.
-{ lib, ... }:
-{
-  imports = [
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "_bashEnvFragments" ]
-      [ "services" "hyperhive" "agent" "_bashEnvFragments" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "allowedRecipients" ]
-      [ "services" "hyperhive" "agent" "allowedRecipients" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "autoCompact" ]
-      [ "services" "hyperhive" "agent" "autoCompact" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "availableModels" ]
-      [ "services" "hyperhive" "agent" "availableModels" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "backendEnvironmentFile" ]
-      [ "services" "hyperhive" "agent" "backendEnvironmentFile" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "cargo" "shortMessages" ]
-      [ "services" "hyperhive" "agent" "cargo" "shortMessages" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "claudeCodePath" ]
-      [ "services" "hyperhive" "agent" "claudeCodePath" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "claudeMarketplaces" ]
-      [ "services" "hyperhive" "agent" "claudeMarketplaces" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "claudePlugins" ]
-      [ "services" "hyperhive" "agent" "claudePlugins" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "claudePluginsAutoUpdate" ]
-      [ "services" "hyperhive" "agent" "claudePluginsAutoUpdate" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "dashboardLinks" ]
-      [ "services" "hyperhive" "agent" "dashboardLinks" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "docs" "enable" ]
-      [ "services" "hyperhive" "agent" "docs" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "docs" "source" ]
-      [ "services" "hyperhive" "agent" "docs" "source" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "effortLevel" ]
-      [ "services" "hyperhive" "agent" "effortLevel" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "extraMcpServers" ]
-      [ "services" "hyperhive" "agent" "extraMcpServers" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "extraWebProxies" ]
-      [ "services" "hyperhive" "agent" "extraWebProxies" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "forge" "url" ]
-      [ "services" "hyperhive" "agent" "forge" "url" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "frontend" "dist" ]
-      [ "services" "hyperhive" "agent" "frontend" "dist" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "frontend" "extraFiles" ]
-      [ "services" "hyperhive" "agent" "frontend" "extraFiles" ]
-    )
-    # `frontend.mergedDist` deliberately has NO entry:
-    # it is `readOnly` and ./frontend.nix already defines it, and a rename
-    # module contributes a *definition* to its target — so a shim for it makes
-    # every evaluation fail with "set multiple times". Nothing could have set
-    # it anyway; a reader of the old path gets "option does not exist",
-    # which says the same thing sooner. Same reasoning as the `hostUsersFile`
-    # exclusion in ../host-modules/deploy.nix.
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "github" "enable" ]
-      [ "services" "hyperhive" "agent" "github" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "gui" "enable" ]
-      [ "services" "hyperhive" "agent" "gui" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "gui" "vncPort" ]
-      [ "services" "hyperhive" "agent" "gui" "vncPort" ]
-    )
-    (lib.mkRenamedOptionModule [ "hyperhive" "icon" ] [ "services" "hyperhive" "agent" "icon" ])
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "logs" "queryUrl" ]
-      [ "services" "hyperhive" "agent" "logs" "queryUrl" ]
-    )
-    # `matrix.enable` is deliberately absent from this list: it has no
-    # replacement option, and a rename pointing at an undeclared option
-    # breaks evaluation for everyone. Both of its spellings are
-    # `mkRemovedOptionModule` in ./default.nix instead.
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "matrix" "url" ]
-      [ "services" "hyperhive" "agent" "matrix" "url" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "matrixAccounts" ]
-      [ "services" "hyperhive" "agent" "matrixAccounts" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "mcp" "bashHttpPort" ]
-      [ "services" "hyperhive" "agent" "mcp" "bashHttpPort" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "mcp" "httpPort" ]
-      [ "services" "hyperhive" "agent" "mcp" "httpPort" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "mcp" "matrixHttpPort" ]
-      [ "services" "hyperhive" "agent" "mcp" "matrixHttpPort" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "mcp" "subagentHttpPort" ]
-      [ "services" "hyperhive" "agent" "mcp" "subagentHttpPort" ]
-    )
-    (lib.mkRenamedOptionModule [ "hyperhive" "model" ] [ "services" "hyperhive" "agent" "model" ])
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "otel" "debug" ]
-      [ "services" "hyperhive" "agent" "otel" "debug" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "otel" "enable" ]
-      [ "services" "hyperhive" "agent" "otel" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "otel" "endpoint" ]
-      [ "services" "hyperhive" "agent" "otel" "endpoint" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "otel" "extraResourceAttributes" ]
-      [ "services" "hyperhive" "agent" "otel" "extraResourceAttributes" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "otel" "metricIntervalMs" ]
-      [ "services" "hyperhive" "agent" "otel" "metricIntervalMs" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "otel" "protocol" ]
-      [ "services" "hyperhive" "agent" "otel" "protocol" ]
-    )
-    (lib.mkRenamedOptionModule [ "hyperhive" "packages" ] [ "services" "hyperhive" "agent" "packages" ])
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "queue" "natsUrl" ]
-      [ "services" "hyperhive" "agent" "queue" "natsUrl" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "queue" "tokenEndpoint" ]
-      [ "services" "hyperhive" "agent" "queue" "tokenEndpoint" ]
-    )
-    # `queue.clientIdFile` / `queue.clientSecretFile` are excluded for the
-    # `mergedDist` reason above: both are `readOnly`, so a shim's definition
-    # collides with the option's own and breaks every evaluation. They are
-    # derived paths no agent config could have set.
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "swarmName" ]
-      [ "services" "hyperhive" "agent" "swarmName" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "useApiKey" ]
-      [ "services" "hyperhive" "agent" "useApiKey" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "user" "gid" ]
-      [ "services" "hyperhive" "agent" "user" "gid" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "user" "name" ]
-      [ "services" "hyperhive" "agent" "user" "name" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "user" "passwordlessSudo" ]
-      [ "services" "hyperhive" "agent" "user" "passwordlessSudo" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "hyperhive" "user" "uid" ]
-      [ "services" "hyperhive" "agent" "user" "uid" ]
-    )
-  ];
-}

nix/docs/default.nix

@@ -212,9 +212,9 @@ let
       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`,
+      (`services.hyperhive.agent.model`, `services.hyperhive.agent.allowedRecipients`,
-      `hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
+      `services.hyperhive.agent.extraMcpServers`, `services.hyperhive.agent.frontend.*`,
-      `hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).
+      `services.hyperhive.agent.forge.*`, `services.hyperhive.agent.matrix.*`, `services.hyperhive.agent.gui.*`).
 
     Regenerate with `nix build .#docs` (bundle), `.#docs-host`,
     `.#docs-swarm`, `.#docs-deploy`, or `.#docs-agent`. Consumed by the

nix/host-modules/default.nix

@@ -87,7 +87,6 @@
     ./swarm.nix
     ./host-ca-removed.nix
     ./nats-callout-removed.nix
-    ./swarm-peers-removed.nix
     ./swarm-required-services.nix
   ];
 }

nix/host-modules/deploy.nix

@@ -26,8 +26,7 @@
 #
 # ⚠️ The renames below are deliberately in this one file rather than
 # spread across the service modules, so all of them have a single home
-# and a single file to delete when the deprecation window closes — the
+# and a single file to delete when the deprecation window closes.
-# shape ./swarm-peers-removed.nix already uses.
 { config, lib, ... }:
 let
   # The swarm UI's own switch, in both spellings. Accepted and ignored: a
@@ -46,7 +45,7 @@ let
     lib.optional (value != null)
       "services.hyperhive.${path} no longer has any effect: swarm-ui now runs wherever swarm-controller runs. Remove this setting; services.hyperhive.deploy.swarm-controller.enable decides it.";
 
-  # Shared by the two removed spellings of the status-publishing secret below.
+  # The removed status-publishing secret below.
   statusSecretRemoved = ''
     hive-c0re reads this hive's status-publishing client secret from the
     swarm's secret store, under the hive's own certificate
@@ -57,101 +56,11 @@ let
 in
 {
   imports = [
-    # Same type, same meaning, new path — so a rename carries it exactly
-    # and existing configs keep evaluating with one warning naming both
-    # paths. Precedent: ./hive-forge/service.nix, ./hive-matrix.nix.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "grafana" "enable" ]
-      [ "services" "hyperhive" "deploy" "grafana" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "grafana" "datasourceUrl" ]
-      [ "services" "hyperhive" "deploy" "grafana" "datasourceUrl" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "grafana" "logsDatasourceUrl" ]
-      [ "services" "hyperhive" "deploy" "grafana" "logsDatasourceUrl" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "grafana" "plugins" ]
-      [ "services" "hyperhive" "deploy" "grafana" "plugins" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "victoriametrics" "enable" ]
-      [ "services" "hyperhive" "deploy" "victoriametrics" "enable" ]
-    )
     (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "victoriametrics" "port" ] ''
       VictoriaMetrics listens on a unix socket in a network namespace of its
       own, and the gateway reaches it there, so it binds no host port. Remove
       this definition.
     '')
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "victorialogs" "enable" ]
-      [ "services" "hyperhive" "deploy" "victorialogs" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "controller" "enable" ]
-      [ "services" "hyperhive" "deploy" "swarm-controller" "enable" ]
-    )
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "controller" "forgeTokenFile" ] ''
-      The controller reads its forge token from the swarm's secret store, under
-      its own certificate, and forgejo-swarm-controller-account in the forge's
-      container puts it there. Remove this definition; the file it named is
-      read by nothing now and can be deleted.
-    '')
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "controller" "authBridgeUrl" ]
-      [ "services" "hyperhive" "deploy" "swarm-controller" "authBridgeUrl" ]
-    )
-    (lib.mkRemovedOptionModule
-      [ "services" "hyperhive" "swarm" "controller" "queue" "clientSecretFile" ]
-      ''
-        The controller reads its queue client secret from the swarm's secret
-        store, under its own certificate (deploy.swarm-controller.baoClientCertFile),
-        and swarm-secret-publish on the host that runs authelia puts it there.
-        Remove this definition; the file it named is read by nothing now and can
-        be deleted.
-      ''
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "authelia" "enable" ]
-      [ "services" "hyperhive" "deploy" "authelia" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "authelia" "usersFile" ]
-      [ "services" "hyperhive" "deploy" "authelia" "usersFile" ]
-    )
-    # `hostClientSecretDir`, `hostUsersFile` and `grafana.socketDir`
-    # deliberately have NO entry here. A rename module contributes a
-    # *definition* to its target, and all three are `readOnly`, which refuses a
-    # second one — so a shim for any of them makes every evaluation fail with
-    # "set multiple times", naming the option's own default as the rival
-    # definition.
-    #
-    # The first two are derived, so nothing could ever have set them and a
-    # shim's only customer is a reader of the old path. `grafana.socketDir` was
-    # a plain settable option; only a test fixture set it in
-    # this tree, but a deployment outside it can have. That setter now fails
-    # evaluation with "option does not exist" at the old path, rather than
-    # being carried to the new one.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "nats" "enable" ]
-      [ "services" "hyperhive" "deploy" "nats" "enable" ]
-    )
-    # `tokenEndpoint` stays under `swarm.*`: it is the swarm IdP's one
-    # address, identical on every hive, where this is "the queue as seen from
-    # here".
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "statusPublish" "natsUrl" ]
-      [ "services" "hyperhive" "deploy" "hive-controller" "statusPublish" "natsUrl" ]
-    )
-    (lib.mkRemovedOptionModule [
-      "services"
-      "hyperhive"
-      "swarm"
-      "statusPublish"
-      "clientSecretFile"
-    ] statusSecretRemoved)
     (lib.mkRemovedOptionModule [
       "services"
       "hyperhive"
@@ -160,27 +69,11 @@ in
       "statusPublish"
       "clientSecretFile"
     ] statusSecretRemoved)
-    # Both old spellings of "run a hive here" forward to the one switch.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "enable" ]
-      [ "services" "hyperhive" "deploy" "hive-controller" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "c0re" "enable" ]
-      [ "services" "hyperhive" "deploy" "hive-controller" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "otel" "enable" ]
-      [ "services" "hyperhive" "deploy" "swarm-otel" "enable" ]
-    )
-    # ⚠️ Not to be confused with `services.hyperhive.otel.clientSecretFile`,
-    # a different option on the hive tier that is not part of this table. A
-    # bare `clientSecretFile` matches five distinct options across the tree.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "otel" "clientSecretFile" ]
-      [ "services" "hyperhive" "deploy" "swarm-otel" "clientSecretFile" ]
-    )
 
+    # Same type, same meaning, new path — so a rename carries it exactly
+    # and existing configs keep evaluating with one warning naming both
+    # paths.
+    #
     # The runner moved from `deploy.forgejo.ci` to `deploy.ci-runner` with
     # every option keeping its type and meaning, so the old paths forward.
     (lib.mkRenamedOptionModule
@@ -219,69 +112,6 @@ in
       [ "services" "hyperhive" "deploy" "bao" "servicesIssuerClientKeyFile" ]
     )
 
-    # The runner toggle sat under `swarm.forge.ci` before `deploy.forgejo.ci`.
-    # Both were per-host, so each forwards straight to its final path.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "ci" "enable" ]
-      [ "services" "hyperhive" "deploy" "ci-runner" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "ci" "name" ]
-      [ "services" "hyperhive" "deploy" "ci-runner" "name" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "ci" "concurrency" ]
-      [ "services" "hyperhive" "deploy" "ci-runner" "concurrency" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "ci" "labels" ]
-      [ "services" "hyperhive" "deploy" "ci-runner" "labels" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "ci" "package" ]
-      [ "services" "hyperhive" "deploy" "ci-runner" "package" ]
-    )
-
-    # The rest of the forge split. What stays under `swarm.forge` is what the
-    # forge IS from any hive's point of view — the names and ports it answers
-    # on, the URLs it advertises, the client id it is registered under; the
-    # two renamed here are what the host running it decides. Its package is
-    # renamed further down with the other `*.package` entries. The two removed
-    # here named host files that the swarm secret store now replaces.
-    #
-    # `mirrors` renames in one entry rather than one per field: it is a single
-    # option of a list-of-submodule type, so the rename carries its whole
-    # value.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "openFirewall" ]
-      [ "services" "hyperhive" "deploy" "forgejo" "openFirewall" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "mirrors" ]
-      [ "services" "hyperhive" "deploy" "forgejo" "mirrors" ]
-    )
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "forge" "sso" "clientSecretFile" ] ''
-      The forge's OIDC client secret is fetched from the swarm secret store
-      (swarm-bao-forge-oidc) into a fixed runtime path. Remove this
-      definition.
-    '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "forge" "hostSwarmControllerTokenFile" ]
-      ''
-        The forge publishes the swarm-controller's forge token to the swarm
-        secret store (forgejo-swarm-controller-account), and the controller
-        reads it there. Remove this definition; the file it named is read by
-        nothing now and can be deleted.
-      ''
-    )
-
-    # The homeserver, split the same way. `swarm.matrix` keeps what it IS to
-    # every hive — the name it answers to, the URLs it is reached on, the
-    # client id it is registered under. These six are what the host
-    # running it decides; its two packages are renamed further down with
-    # the other `*.package` entries. ⚠️ `enable` is NOT here: its shim lives in
-    # ./hive-matrix.nix, so that file is the one
-    # to check before assuming this table is the whole matrix story.
-    #
     # The homeserver's port and its firewall switch, removed rather than
     # renamed: tuwunel listens on a unix socket only the gateway reaches, so
     # there is no host port to choose or open.
@@ -291,111 +121,20 @@ in
       Remove this definition. Clients and federation peers reach it at
       services.hyperhive.swarm.matrix.gatewayHost.
     '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "matrix" "openFirewall" ] ''
-      The homeserver no longer listens on a host port, so there is no port
-      to open. Remove this definition. Reach from outside the host goes
-      through the gateway: services.hyperhive.gateway.openFirewall.
-    '')
     (lib.mkRemovedOptionModule [ "services" "hyperhive" "deploy" "matrix" "openFirewall" ] ''
       The homeserver no longer listens on a host port, so there is no port
       to open. Remove this definition. Reach from outside the host goes
       through the gateway: services.hyperhive.gateway.openFirewall.
     '')
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "matrix" "trustedServers" ]
-      [ "services" "hyperhive" "deploy" "matrix" "trustedServers" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "matrix" "maxRequestSize" ]
-      [ "services" "hyperhive" "deploy" "matrix" "maxRequestSize" ]
-    )
-    # Both spellings of the registration token, removed rather than renamed:
-    # the homeserver does not accept a shared registration secret at all,
-    # so there is no path to point a definition at. Accounts are created by
-    # the swarm's appservice.
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "matrix" "registrationTokenFile" ] ''
-      The matrix registration token is gone: swarm-controller creates accounts
-      as the swarm's appservice instead, so there is no shared secret for
-      tuwunel to check. Remove this definition — nothing needs replacing.
-      The old token file at /var/lib/hyperhive/matrix-register-token is read by
-      nothing now and can be deleted. See docs/integrations/matrix.md.
-    '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "deploy" "matrix" "registrationTokenFile" ] ''
-      The matrix registration token is gone: swarm-controller creates accounts
-      as the swarm's appservice instead, so there is no shared secret for
-      tuwunel to check. Remove this definition — nothing needs replacing.
-      The old token file at /var/lib/hyperhive/matrix-register-token is read by
-      nothing now and can be deleted. See docs/integrations/matrix.md.
-    '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "swarm" "matrix" "gui" "enable" ] ''
-      The matrix web client has no on/off switch: every host that runs the
-      homeserver serves it at services.hyperhive.swarm.matrix.gatewayHost,
-      and the swarm UI links to it. Remove this definition.
-    '')
     (lib.mkRemovedOptionModule [ "services" "hyperhive" "deploy" "matrix" "gui" "enable" ] ''
       The matrix web client has no on/off switch: every host that runs the
       homeserver serves it at services.hyperhive.swarm.matrix.gatewayHost,
       and the swarm UI links to it. Remove this definition.
     '')
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "matrix" "sso" "clientSecretFile" ]
-      [ "services" "hyperhive" "deploy" "matrix" "sso" "clientSecretFile" ]
-    )
 
-    # Retention is read only where the container is defined, so it is a
+    # The hive CA's lifetime and its leaves', removed rather than renamed: no
-    # decision of the host running the store rather than something the swarm
+    # hive CA is generated, and the store's per-hive role sets the gateway
-    # agrees on. The two stores keep their domain and port in `swarm.*`,
+    # leaf's lifetime.
-    # because a client hive needs those to reach them; `package` followed
-    # `enable` and `retentionPeriod` across in a later slice.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "victoriametrics" "retentionPeriod" ]
-      [ "services" "hyperhive" "deploy" "victoriametrics" "retentionPeriod" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "victorialogs" "retentionPeriod" ]
-      [ "services" "hyperhive" "deploy" "victorialogs" "retentionPeriod" ]
-    )
-
-    # The switch over all of the above. `allSwarmServices` says whether THIS
-    # host runs every service the swarm requires; those services are
-    # required of the SWARM, so the name is about the swarm rather than this
-    # host's wiring.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "enableRequiredServices" ]
-      [ "services" "hyperhive" "deploy" "allSwarmServices" ]
-    )
-
-    # The mode above that one lives under `deploy`, not at the TOP of
-    # `services.hyperhive`: that namespace is everything about hyperhive, not
-    # the settings of a single hive. `singleHostSwarm` names what the mode
-    # asserts — the whole swarm runs on this host — instead of its mechanism.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "enableAllLocalDefaults" ]
-      [ "services" "hyperhive" "deploy" "singleHostSwarm" ]
-    )
-
-    # The hive TLS state dir lives under `deploy.hive-controller` (the
-    # hive-c0re daemon's namespace), not at the TOP of `services.hyperhive`,
-    # which is everything about hyperhive rather than the settings of one hive.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "tls" "stateDir" ]
-      [ "services" "hyperhive" "deploy" "hive-controller" "tls" "stateDir" ]
-    )
-    # The hive CA's lifetime and its leaves', both spellings, removed rather
-    # than renamed: no hive CA is generated, and the store's per-hive role
-    # sets the gateway leaf's lifetime.
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "tls" "caValidityDays" ] ''
-      No hive CA is generated any more: the gateway leaf is issued by the
-      secret store's pki mount, whose per-hive role sets its lifetime
-      (services.hyperhive.deploy.bao.servicesPkiLeafTtlHours). Remove this
-      definition. See docs/swarm/ca.md.
-    '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "tls" "leafValidityDays" ] ''
-      No hive CA is generated any more: the gateway leaf is issued by the
-      secret store's pki mount, whose per-hive role sets its lifetime
-      (services.hyperhive.deploy.bao.servicesPkiLeafTtlHours). Remove this
-      definition. See docs/swarm/ca.md.
-    '')
     (lib.mkRemovedOptionModule
       [ "services" "hyperhive" "deploy" "hive-controller" "tls" "caValidityDays" ]
       ''
@@ -415,98 +154,12 @@ in
       ''
     )
 
-    # The WireGuard mesh, whole. Unlike every rename above this one covers a
+    # `deploy.swarm-ui` keeps only its ignored `enable` (declared below); its
-    # namespace rather than a toggle: nothing under it is a fact another hive
+    # `package` is the controller's UI package.
-    # reads. A peer needs this host's `wireguardEndpoint` — the roster entry
-    # in ./swarm.nix, which stays — and nothing about the interface this host
-    # brings up. `listenPort` follows for the same reason and is easy to read
-    # the other way: it is what this host *binds*, while the port a peer
-    # *dials* is the one inside `wireguardEndpoint`.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "wireguard" "enable" ]
-      [ "services" "hyperhive" "deploy" "wireguard" "enable" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "wireguard" "privateKeyFile" ]
-      [ "services" "hyperhive" "deploy" "wireguard" "privateKeyFile" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "wireguard" "address" ]
-      [ "services" "hyperhive" "deploy" "wireguard" "address" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "wireguard" "listenPort" ]
-      [ "services" "hyperhive" "deploy" "wireguard" "listenPort" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "wireguard" "persistentKeepalive" ]
-      [ "services" "hyperhive" "deploy" "wireguard" "persistentKeepalive" ]
-    )
-
-    # Which build a service runs is a decision of the host that runs it, so
-    # every `*.package` follows its `enable` across. Left in separate
-    # namespaces they split one client's two halves, as `gui.enable` and
-    # `gui.package` would.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "matrix" "package" ]
-      [ "services" "hyperhive" "deploy" "matrix" "package" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "matrix" "gui" "package" ]
-      [ "services" "hyperhive" "deploy" "matrix" "gui" "package" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "grafana" "package" ]
-      [ "services" "hyperhive" "deploy" "grafana" "package" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "victorialogs" "package" ]
-      [ "services" "hyperhive" "deploy" "victorialogs" "package" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "victoriametrics" "package" ]
-      [ "services" "hyperhive" "deploy" "victoriametrics" "package" ]
-    )
-    # With these two `services.hyperhive.swarm.ui` holds nothing at all: its
-    # `enable` is an ignored switch (declared below) and its `package` is
-    # renamed here. `deploy.swarm-ui` keeps only its ignored `enable`.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "ui" "package" ]
-      [ "services" "hyperhive" "deploy" "swarm-controller" "ui" "package" ]
-    )
     (lib.mkRenamedOptionModule
       [ "services" "hyperhive" "deploy" "swarm-ui" "package" ]
       [ "services" "hyperhive" "deploy" "swarm-controller" "ui" "package" ]
     )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "nats" "authPackage" ]
-      [ "services" "hyperhive" "deploy" "nats" "authPackage" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "authelia" "package" ]
-      [ "services" "hyperhive" "deploy" "authelia" "package" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "authelia" "bridgePackage" ]
-      [ "services" "hyperhive" "deploy" "authelia" "bridgePackage" ]
-    )
-    # ⚠️ `swarm-controller`, not `hive-controller` — see the note in
-    # ./swarm-controller.nix. Both namespaces exist, so the wrong target here
-    # lands on a live option in hive-c0re's tree instead of failing.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "controller" "package" ]
-      [ "services" "hyperhive" "deploy" "swarm-controller" "package" ]
-    )
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "controller" "swarmctlPackage" ]
-      [ "services" "hyperhive" "deploy" "swarm-controller" "swarmctlPackage" ]
-    )
-    # ⚠️ `deploy.forgejo`, not `deploy.forge` — the deploy-side name differs
-    # from the swarm-side one here, as it does for the controller and the UI.
-    (lib.mkRenamedOptionModule
-      [ "services" "hyperhive" "swarm" "forge" "package" ]
-      [ "services" "hyperhive" "deploy" "forgejo" "package" ]
-    )
   ];
 
   # ⚠️ Only `deploy.forgejo.enable` is declared here. The rest of

nix/host-modules/hive-c0re/environment.nix

@@ -67,13 +67,13 @@ in
 }
 // lib.optionalAttrs (!config.services.hyperhive.github.enable) {
   # GitHub integration is on by default; only signal the OFF override to
-  # meta.rs, which then injects `hyperhive.github.enable = false` into
+  # meta.rs, which then injects `services.hyperhive.agent.github.enable = false` into
   # every agent. See services.hyperhive.github.enable.
   HYPERHIVE_GITHUB_DISABLED = "1";
 }
 // lib.optionalAttrs config.services.hyperhive.otel.enable (
   # Hive-wide OTEL config -> read by meta.rs::otel_config and
-  # injected as build-time `hyperhive.otel.*` into every agent.
+  # injected as build-time `services.hyperhive.agent.otel.*` into every agent.
   # Endpoint presence is the enable signal on the meta side; the
   # optional fields are only emitted when set so absent values
   # don't render no-op env lines.
@@ -172,7 +172,7 @@ in
   # fallback reads as harmless because hive-c0re shares the host netns —
   # but the value is handed to *agents*, which do not, so `127.0.0.1`
   # there names the agent itself. An absent forward leaves
-  # `hyperhive.matrix.url` null and the daemon no-ops; that is the honest
+  # `services.hyperhive.agent.matrix.url` null and the daemon no-ops; that is the honest
   # answer when there is no matrix vhost to point at.
   HIVE_MATRIX_URL = "http://${config.services.hyperhive.swarm.matrix.gatewayHost}";
 }

nix/host-modules/hive-c0re/options.nix

@@ -76,7 +76,7 @@
       description = ''
         URL of the narrow `docs/` source (no fragment). Inlined into the
         generated meta `flake.nix` at `inputs.hyperhive-docs.url` and
-        threaded to each agent as `hyperhive.docs.source`, from which the
+        threaded to each agent as `services.hyperhive.agent.docs.source`, from which the
         harness resolves `$HIVE_DOCS_DIR`. Its own store path — separate
         from `hyperhiveFlake` — so a doc edit only re-locks this input
         instead of rebuilding every agent container.