docs(#2862): document the push side and regenerate the CLI reference

docs/tools/hivectl-cli.md is generated by `hivectl markdown-docs` and
diffed against a fresh run by the hivectl-docs flake check, so adding
the push verb without regenerating it would have failed CI. The
regeneration also retires two copies of a sentence describing the
cross-hive leg as an ssh pipe that "isn't wired up yet" -- ssh was
dropped when the WireGuard mesh became the authentication, and the leg
is wired up now.

snapshot-store.md documented only the receiving host, so a reader had
no way to learn how a pushing hive is told where the store is. It now
covers services.hyperhive.swarm.snapshotStore, including why address
has no default and port does: an address is a deployment fact that
cannot be guessed, a port is a convention both ends read from the same
docs. It also states the namespace rule the two options illustrate --
swarm.* describes the swarm as seen from here, a bare
services.hyperhive.<service> describes a role this host performs.

swarm.md never mentioned the store even though the option lives in its
namespace, so a reader configuring swarm.peers had no signal it exists.

docs/snapshot-store.md

@@ -41,6 +41,41 @@ Note that the mesh is gated on `swarm.wireguard.enable`, **not** on
 `c0re.enable` --- a store host runs no hive and would otherwise get no
 `wg-hive` interface at all.
 
+## Pointing a hive at it
+
+The block above configures the host that *receives*. Every hive that
+*pushes* separately needs to be told where the store is:
+
+```nix
+services.hyperhive.swarm.snapshotStore = {
+  address = "10.100.0.9";  # the store's mesh address, no prefix
+  port = 51821;            # optional; must match the receiver's port
+};
+```
+
+Two deliberate asymmetries in that pair, both easy to misread as
+inconsistency:
+
+- **`address` has no default.** It is a deployment fact a pushing hive
+  cannot derive, and a wrong guess means streaming an agent's state at
+  whatever happens to answer. Unset, a push fails naming this option.
+- **`port` does default** (`51821`), because it is a convention both
+  ends read from the same option docs --- a default there is
+  coordination, not a guess.
+
+Note the option lives under `swarm.*` while the receiving host's lives
+under `services.hyperhive.snapshotStore`. That is the distinction the
+two namespaces carry throughout: `swarm.*` describes *the swarm* as seen
+from this host, and a bare `services.hyperhive.<service>` describes *a
+role this host performs*. A store host sets both --- one to run the
+receiver, one only if it also runs a hive that pushes.
+
+With it set, `hivectl agent <name> subvol snapshot push <label>
+[--parent <label>]` streams a snapshot straight into the store. There is
+no destination argument, because a swarm has exactly one store (see
+[One subvolume per agent, not per hive](#one-subvolume-per-agent-not-per-hive)),
+and no credential argument, because the mesh is the authentication.
+
 ## The mesh is the authentication
 
 There are no certificates here, and no key material of its own. That is

docs/swarm.md

@@ -221,8 +221,22 @@ other side initiates. With keepalive on, the NAT hole stays open.
 If both hosts are behind NAT, a STUN relay or a third host (exit node)
 is required. Out of scope for v0.
 
+## Snapshot store
+
+One further option lives in this namespace but is documented with the
+service it points at: `services.hyperhive.swarm.snapshotStore.{address,
+port}` tells this hive where the swarm's `btrfs receive` endpoint is, so
+`hivectl agent <name> subvol snapshot push` has somewhere to stream to.
+
+It is genuinely swarm-scoped rather than per-peer — a swarm has exactly
+one store, because the receiver keys destinations by *agent* so a
+migrating agent keeps one unbroken incremental chain. See
+[snapshot-store.md](snapshot-store.md).
+
 ## Cross-references
 
+- `docs/snapshot-store.md` — the swarm's `btrfs receive` endpoint, and
+  the `swarm.snapshotStore` option that points a hive at it
 - `docs/conventions.md` § Hive identity — env vars, qualified labels
 - `docs/matrix.md` — matrix federation, TLS cert auto-generation,
   firewall posture

docs/tools/hivectl-cli.md

@@ -42,6 +42,7 @@ This document contains the help content for the `hivectl` command-line program.
 * [`hivectl agent subvol snapshot create`↴](#hivectl-agent-subvol-snapshot-create)
 * [`hivectl agent subvol snapshot delete`↴](#hivectl-agent-subvol-snapshot-delete)
 * [`hivectl agent subvol snapshot send`↴](#hivectl-agent-subvol-snapshot-send)
+* [`hivectl agent subvol snapshot push`↴](#hivectl-agent-subvol-snapshot-push)
 * [`hivectl list-agents`↴](#hivectl-list-agents)
 * [`hivectl quota-enable`↴](#hivectl-quota-enable)
 * [`hivectl approvals`↴](#hivectl-approvals)
@@ -562,7 +563,8 @@ Read-only snapshots of this agent's state subvolume
 
 * `create` — Create a read-only snapshot (agent must already be a subvolume)
 * `delete` — Delete a snapshot created by `subvol snapshot create`
-* `send` — Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
+* `send` — Export a snapshot to a local file via `btrfs send` — the local-file half of the inter-hive migration transport (`push` is the network half). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
+* `push` — Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport
 
 
 
@@ -592,7 +594,7 @@ Delete a snapshot created by `subvol snapshot create`
 
 ## `hivectl agent subvol snapshot send`
 
-Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
+Export a snapshot to a local file via `btrfs send` — the local-file half of the inter-hive migration transport (`push` is the network half). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
 
 **Usage:** `hivectl agent subvol snapshot send [OPTIONS] --dest <DEST> <LABEL>`
 
@@ -607,6 +609,26 @@ Export a snapshot to a local file via `btrfs send` (the local-file half of inter
 
 
 
+## `hivectl agent subvol snapshot push`
+
+Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport.
+
+Nothing is staged locally: `btrfs send` writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here.
+
+There is no destination argument: a swarm has one store, read from `services.hyperhive.swarm.snapshotStore`.
+
+**Usage:** `hivectl agent subvol snapshot push [OPTIONS] <LABEL>`
+
+###### **Arguments:**
+
+* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
+
+###### **Options:**
+
+* `--parent <PARENT>` — Optional parent snapshot label for an incremental send (`btrfs send -p`) — must be an existing, older snapshot of the same agent, and must already be present on the receiver. Omit for a full send
+
+
+
 ## `hivectl list-agents`
 
 Show all managed agents with their status and technical state.