diff --git a/docs/ci.md b/docs/ci.md
index 6c34ddb9..5c1f9d49 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -33,6 +33,40 @@ Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's
 3. If `.runner` is absent (first boot or purged above): fetch a fresh registration token from `GET /api/v1/admin/runners/registration-token`. Retries for 30s in case forge is still starting. Writes `TOKEN=<real>` to `/run/hive-ci/runner-token`.
 4. Container starts with `/run/hive-ci/runner-token` bind-mounted read-only. `gitea-actions-runner` reads the token, registers itself, and persists credentials to `.runner`. On subsequent boots step 2 validates these credentials and fast-paths past registration.
 
+## Actions checkout mirror
+
+When `forge.ci.enable` is set, hive-c0re auto-seeds an
+`actions/checkout` pull-mirror on the local forge and sets Forgejo's
+`DEFAULT_ACTIONS_URL` to point at the local instance. This means CI
+`uses: actions/checkout@vN` steps resolve entirely on loopback — no
+external DNS on the CI critical path.
+
+The mirror is seeded by **hive-c0re** itself during its forge
+provisioning sweep (`forge.rs::ensure_mirrors`). The nix module
+forwards the effective mirror list as `HYPERHIVE_FORGE_MIRRORS` in the
+`hive-c0re` service environment (JSON-encoded `[{upstream, dest}]`
+list). hive-c0re already holds the admin token for the rest of the
+forge provisioning sweep (orgs, agent accounts, etc.), so mirror
+seeding lives in the same place rather than a separate host-side unit.
+
+**General-purpose mirrors**: you can pre-seed any external repo as a
+pull-mirror via `services.hyperhive.forge.mirrors`:
+
+```nix
+services.hyperhive.forge.mirrors = [
+  { upstream = "https://github.com/actions/checkout"; dest = "actions/checkout"; }
+  { upstream = "https://github.com/example/tool";    dest = "mirrors/tool"; }
+];
+```
+
+Each entry is created as a real Forgejo pull-mirror — not a one-off
+clone. Forgejo re-syncs the mirror on every pull (`git-upload-pack`
+request), so a DNS blip during that sync will propagate back to the
+runner as a hard `git clone` failure. The
+`<owner>` org in `dest` is auto-created. Keep mirror dests out of the
+hive-c0re-managed namespaces (`config/`, `shared/`, `agents/`, `core/`)
+to avoid provisioning collisions.
+
 ## CI workflow
 
 The single CI job is defined in `.forgejo/workflows/ci.yml`: