nix: add breaking-change note to each openFirewall description (argus #653)

argus picked option (a) on #653: put the upgrade note in each option's
`description` so it shows up in `nix flake show` + the rendered
options docs, right next to the option itself. cheapest option, no
eval-time noise (a `warnings` block would fire on every new
deployment that wants false — the normal case now).

Appended a `**Breaking change as of #651**` paragraph to each of the
three `openFirewall` descriptions, naming the exact option string the
operator needs to set to restore the old behaviour.

Gateway's note specifically calls out that external reach is the
common case (operator's primary entry point), so the upgrade hint
is most likely needed there.

nix/modules/hive-forge.nix

@@ -87,12 +87,22 @@ in
 
     openFirewall = lib.mkOption {
       type = lib.types.bool;
-      default = true;
+      default = false;
+      example = true;
       description = ''
-        Open `httpPort` + `sshPort` in the host firewall. Off when
-        the forge should only be reachable from inside the host.
-        (The container shares host netns, so this is the only
-        firewall layer that matters.)
+        Open `httpPort` + `sshPort` in the host firewall. Off by
+        default (#651, secure-by-default): the forge is reachable
+        from the host + every agent container via `localhost` either
+        way (shared netns), so the firewall opens only matter for
+        access from outside the host. Flip to `true` when you want
+        the operator's browser / external git clients to hit the
+        forge directly. (The container shares host netns, so this
+        is the only firewall layer that matters.)
+
+        **Breaking change as of #651**: this used to default to
+        `true`. If you relied on the old default for external
+        reach, add `services.hyperhive.forge.openFirewall = true;`
+        to your host config before rebuilding.
       '';
     };
   };

nix/modules/hive-gateway.nix

@@ -82,11 +82,23 @@ in
 
     openFirewall = lib.mkOption {
       type = lib.types.bool;
-      default = true;
+      default = false;
+      example = true;
       description = ''
-        Open `port` in the host firewall. Off when the gateway should
-        only be reachable from inside the host (e.g. behind another
-        reverse proxy that handles TLS termination).
+        Open `port` in the host firewall. Off by default (#651,
+        secure-by-default). Flip to `true` to expose the gateway to
+        the operator's browser / external clients — required for any
+        out-of-host reach, since the agents themselves talk to
+        hive-c0re via the per-agent unix sockets and don't need the
+        nginx vhost. Leave off when running behind another reverse
+        proxy (e.g. caddy / traefik on the host) that handles TLS
+        termination + forwards to `port`.
+
+        **Breaking change as of #651**: this used to default to
+        `true`. If you relied on the old default for external reach
+        (the common case — the gateway is the operator's primary
+        entry point), add `services.hyperhive.gateway.openFirewall = true;`
+        to your host config before rebuilding.
       '';
     };
 

nix/modules/hive-matrix.nix

@@ -98,12 +98,21 @@ in
 
     openFirewall = lib.mkOption {
       type = lib.types.bool;
-      default = true;
+      default = false;
+      example = true;
       description = ''
-        Open `httpPort` in the host firewall. Off when the
-        homeserver should only be reachable from inside the host
-        (e.g. while bringing the integration up before announcing
-        it to other hives).
+        Open `httpPort` in the host firewall. Off by default (#651,
+        secure-by-default): the homeserver is reachable from the
+        host + every agent container via `localhost` either way
+        (shared netns), so the firewall open only matters for
+        access from outside the host. Flip to `true` when announcing
+        the homeserver to other hives or when an external matrix
+        client needs to reach the client-server API directly.
+
+        **Breaking change as of #651**: this used to default to
+        `true`. If you relied on the old default for external reach,
+        add `services.hyperhive.matrix.openFirewall = true;` to
+        your host config before rebuilding.
 
         Note: federation (the matrix-spec well-known port 8448) is
         intentionally not opened here. tuwunel serves the federation