From 7b23b53b758d72e5ff653fde7d1ff71f8cc0a5ab Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 31 Jul 2026 22:07:55 +0200 Subject: [PATCH] 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. 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 | 35 +++++++++++++++++++++++++++++++++++ docs/swarm.md | 14 ++++++++++++++ docs/tools/hivectl-cli.md | 26 ++++++++++++++++++++++++-- 3 files changed, 73 insertions(+), 2 deletions(-) diff --git a/docs/snapshot-store.md b/docs/snapshot-store.md index 8bacdd21..74003730 100644 --- a/docs/snapshot-store.md +++ b/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.` 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 subvol snapshot push