feat(installer): detect a blocked container registry + guide to mirror/offline (#585)

[shujaatTracebloc]

What & why

Child 4/4 of #578 (network resilience) — first slice: detection + clean guidance. (Contributes to #585; the mirror/air-gap wiring and the offline image bundle are follow-on slices — see below.)

Some sites hard-block Docker Hub / GHCR outright, so the images aren't reachable directly at all — distinct from a proxy or TLS-inspection (covered by #582/#583). This slice makes the installer recognize that specific case and guide the user to the mirror / offline options in plain language, staying a clean preflight stop rather than a raw pull failure (builds on #576/#577/#582).

Changes

• preflight.sh — after the existing connectivity hints, if any failed critical host is a container registry (registry-1.docker.io / auth.docker.io / ghcr.io), print mirror/offline guidance pointing at docs/INSTALL.md. Reuses the connectivity probe from Network resilience (1/4): preflight network probe + plain-language network profile #582; no new network calls.
• install-k8s.ps1 — same, via a $regBlocked flag in Test-Preflight (cross-platform, one-to-one copy).
• docs/INSTALL.md — new "Blocked container registry (mirror / air-gapped)" section: point the install at a reachable mirror via TRACEBLOC_VALUES_FILE overriding images.*.registry (+ dockerRegistry creds for a private mirror), with a concrete values example; note the air-gapped-bundle path (tracked for the next slice); and state the honest limit (a site that blocks the registries and has no mirror and won't accept an offline bundle can't be served).

Scope note (this is one slice of the #585 epic)

• ✅ This PR: detection of a blocked registry + plain-language guidance + docs for the mirror path (which the chart + TRACEBLOC_VALUES_FILE already support).
• ⬜ Follow-on slices: a one-knob mirror UX (single env → remap all images) and the air-gapped image bundle (pre-load images into the cluster) for fully offline sites.

Acceptance mapping

• "Detection + clean guidance, never a raw failure" → ✅ this slice.
• "A blocked-registry site can complete via mirror or air-gapped bundle" → mirror path documented + usable today via TRACEBLOC_VALUES_FILE; air-gapped bundle is the next slice.

Tests

• bats: the registry-block guidance fires when a registry host is blocked, and does not fire when only a non-registry host (the backend API) fails.
• Pester:Test-Preflight carries the $regBlocked detection + the guidance line + the docs pointer.
• Full Pester 448/0/9; preflight.bats 124/0; check-facts + check-style + manifest --check clean (preflight.sh/install-k8s.ps1 are manifested — manifest regenerated).

---

Note

Low Risk
Installer preflight messaging and documentation only; no change to pull logic or cluster provisioning.

Overview
When preflight sees Docker Hub / GHCR as unreachable (not just any egress failure), the installer now adds a dedicated hint about using a mirror via TRACEBLOC_VALUES_FILE or a future air-gapped bundle, instead of leaving users with only the generic allowlist message. The same logic is in preflight.sh and install-k8s.ps1 ($regBlocked).

docs/INSTALL.md gains a Blocked container registry section with a concrete mirror-values.yaml example (images.*.registry, ingestor repository, optional dockerRegistry creds), a pointer to the offline-bundle work (#585), and the honest limit when no mirror or bundle is possible.

Tests assert registry-only failures trigger the new guidance (bats + Pester); non-registry failures do not. Script manifest hashes are updated.

^{Reviewed by Cursor Bugbot for commit aa973d9. Bugbot is set up for automated code reviews on this repo. Configure here.}