docs: add ci.md — hive-ci Forgejo Actions runner guide

CLAUDE.md

@@ -325,6 +325,8 @@ docs/
   swarm.md             multi-hive swarm config: peer declaration, TLS trust
                        (CA vs certFingerprint), bilateral setup, identity
                        env vars, matrix federation pointer
+  ci.md                hive-ci Forgejo Actions runner: options, container
+                       shape, auto-registration flow, nix sandbox note
 ```
 
 ## Reading paths

docs/ci.md

@@ -0,0 +1,81 @@
+# hive-ci — Forgejo Actions runner
+
+The `hive-ci` module adds a Forgejo Actions runner to the hive so
+workflows in the hyperhive repo (and any operator-managed repos on
+the hive forge) can run on the same host. Disabled by default.
+
+## Enabling
+
+```nix
+services.hyperhive.forge.ci = {
+  enable = true;
+  name   = "prod-hive";    # shows in Forgejo admin panel; default = hostname
+};
+```
+
+Requires `services.hyperhive.forge.enable = true` (the runner
+registers against the hive-forge Forgejo instance). The module
+asserts this at eval time.
+
+## Options
+
+| option | default | description |
+|---|---|---|
+| `forge.ci.enable` | `false` | opt-in; off by default |
+| `forge.ci.name` | hostname | runner name in Forgejo admin panel |
+| `forge.ci.concurrency` | `2` | maximum parallel jobs |
+| `forge.ci.labels` | `["hive-ci:host"]` | runner labels (`<name>:<scheme>`) |
+| `forge.ci.package` | `pkgs.gitea-actions-runner` | override the runner binary |
+
+The `host` scheme in labels means jobs run directly inside the
+`hive-ci` container (no docker/podman). Workflow files target this
+runner with:
+
+```yaml
+runs-on: [hive-ci]
+```
+
+## Container shape
+
+`hive-ci` is an ephemeral-false nixos-container sharing the host
+network namespace (`privateNetwork = false`) so it reaches the
+hive-forge Forgejo instance at `localhost:<forge-http-port>` without
+needing a routed address.
+
+Bind mounts:
+- `/run/hive-ci/core-token` ← `coreTokenPath` (host's forge
+  admin token, read-only). Used only on first boot for registration.
+
+The container has `git` in `systemPackages`; everything else a
+workflow needs (rust tools, nix, etc.) is either pulled in by the
+workflow itself via `nix flake check` or is part of the base NixOS
+closure.
+
+Nix sandboxing is disabled in the container (`sandbox-fallback =
+true`) because nspawn containers can't create the user namespaces
+that the Nix sandbox requires. See `docs/gotchas.md` for the
+general nspawn sandbox note.
+
+## Auto-registration
+
+On first boot an `ExecStartPre` script (`hive-ci-autoregister`) runs
+before the runner service:
+
+1. Reads the hive-c0re admin token from `/run/hive-ci/core-token`.
+2. Calls `GET /api/v1/admin/runners/registration-token` on the forge
+   (retrying for up to 30 s while forge starts).
+3. Writes the registration token to `/run/hive-ci/runner-token`.
+4. The runner service picks it up and registers, writing credentials
+   to `/var/lib/gitea-runner/hive/.runner`.
+
+On subsequent boots the `.runner` credentials file already exists;
+the script writes a dummy token and exits — the runner ignores it
+and reuses its stored credentials.
+
+No manual token handling is needed. The whole flow is automatic on
+`nixos-container start`.
+
+## Cross-references
+
+- `docs/forge.md` — hive-forge setup (prerequisite)
+- `docs/gotchas.md` — nspawn sandbox-fallback note