seed a hyperhive/hyperhive mirror so update_meta finds it on a fresh swarm

docs/1-getting-started/nixos.md

@@ -85,6 +85,21 @@ services.hyperhive = {
 Run `nixos-rebuild switch --flake .#my-host`. The swarm UI then answers at
 `https://<swarm.domain>/`.
 
+### The hyperhive mirror
+
+The swarm controller pins the hive's flake inputs to a commit of hyperhive on
+the swarm's own forge, so the forge needs a `hyperhive/hyperhive` repo before
+the first agent builds. On a host that runs the forge and the controller,
+the controller creates it as a pull-mirror of
+`https://forge.darkest.space/hyperhive/hyperhive`. You run no extra step.
+
+| option                             | what it does                                                                                                                                                                                                                                           |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `deploy.forgejo.hyperhiveUpstream` | The clone URL the mirror pulls from. Set another URL to mirror a fork, or `null` to seed nothing and provide the repo yourself. The controller creates the mirror only if `hyperhive/hyperhive` doesn't exist, so a repo already there stays as it is. |
+
+Without the repo, the first agent's `update_meta` job step fails with
+`hyperhive/hyperhive is empty or absent on the swarm forge`.
+
 ## Everything else is optional
 
 Leave the other options at their defaults until you need them:

docs/1-getting-started/setup.md

@@ -149,7 +149,10 @@ swarmctl agent create iris --hive firsthive
 
 The controller provisions iris's identity, forge user and config repo
 (`agent-configs/iris`, from the default template), then has the hive build
-and start the container. It returns once the scheduler queues the job — watch the
+and start the container. The hive builds from a copy of hyperhive on the swarm's own forge: the
+controller mirrors it there as `hyperhive/hyperhive` on a fresh swarm, so the
+first agent needs no extra step (see
+[`nixos.md`](nixos.md#the-hyperhive-mirror)). It returns once the scheduler queues the job — watch the
 swarm UI's job view for progress.
 
 Later config changes are PRs on `agent-configs/iris`; you merge them on the

docs/2-handbook/swarm/README.md

@@ -412,7 +412,8 @@ one per hive. It ensures them at start and every five minutes after
   repo with no `main` rule alone;
 - the pull-mirrors from `deploy.forgejo.mirrors` on the controller's
   host (with the `actions/checkout` and `actions/upload-artifact` ones
-  `deploy.forgejo.actionsFromSelf` adds);
+  `deploy.forgejo.actionsFromSelf` adds, and `hyperhive/hyperhive` from
+  `deploy.forgejo.hyperhiveUpstream`);
 - `internal/docs` (private) and `internal/knowledge` (public, with a
   seed `README.md` while empty);
 - the `agent-configs` org avatar

docs/4-implementation/scheduler/ci.md

@@ -251,6 +251,14 @@ environment (JSON-encoded `[{upstream, dest}]` list). It reads the list of
 the host the controller runs on: mirrors declared on any other host aren't
 seeded, and evaluation warns about them.
 
+**The hyperhive mirror**: the same list carries `hyperhive/hyperhive`, from
+`services.hyperhive.deploy.forgejo.hyperhiveUpstream` (default
+`https://forge.darkest.space/hyperhive/hyperhive` on a host that runs the
+controller, unset elsewhere). The controller creates the mirror only when
+`hyperhive/hyperhive` doesn't exist, and it leaves a repo that exists but is
+not a mirror unchanged. `deploy.forgejo.mirrors` takes precedence for the same
+`dest`.
+
 **General-purpose mirrors**: you can pre-seed any external repo as a
 pull-mirror via `services.hyperhive.deploy.forgejo.mirrors`: