[Gap]: Document preflight checks for Stacklok Enterprise Platform

[glageju]

What needs documentation?

Document the preflight checks feature for the Stacklok Enterprise Platform
Helm chart: the shipped Preflight custom resource, the advisory
kubectl preflight workflow on the Helm CLI install path, and the opt-in
preflight.enforce=true in-cluster blocking mode.

Fold this into the existing install guides rather than adding a new page:

• docs/platform/enterprise-platform/deployment.mdx — new "Run preflight
  checks" section between "What the chart includes" and "Deploy with Helm".
• docs/platform/enterprise-platform/airgap-install.mdx — a short addition
  covering the air-gapped/offline behavior of the default spec.

No new page and no sidebar changes are needed.

Design notes (click to expand)

deployment.mdx — "Run preflight checks" section

Place between "What the chart includes" and "Deploy with Helm". Cover, in
order:

1. Framing — the umbrella chart ships a Preflight custom resource as a
   labeled Secret; helm template ... | kubectl preflight - analyzes real
   prerequisites automatically. Catches Kubernetes version below the chart
   floor, tight node capacity, unreachable OIDC issuer, missing signing-key
   Secret, before they surface later as failed pods.

2. Install the CLI plugin — recommend the pinned binary release from
   replicatedhq/troubleshoot (the version Stacklok's CI validates against);
   note kubectl krew install preflight as a quicker but unpinned
   alternative that can silently drift ahead of the tested version.

3. Run it against your real values — use the real values.yaml from
   the "Configure values" step, not an empty render, since the opt-in
   analyzers (OIDC, signing-key, postgres) only render when their values
   are set.

4. What it checks — a table:

   Check	Renders when	Outcome
   Kubernetes version	Always	fail below 1.28 (chart floor)
   Node capacity (CPU/memory)	Always	warn if tight, smallest node
   Distribution	Always	warn on OpenShift OCP
   Egress reachability	preflight.checkEgress=true	warn only; off by default, always fails in air gap
   Registry database reachability	registryServer.enabled + run-time preflightDatabaseUri	fail if unreachable
   OIDC issuer reachability	enterpriseManager.enabled=true + idpConfig.issuer set	fail if unreachable/misconfigured
   Signing-key Secret exists	enterpriseManager.enabled=true	fail if signingConfig.existingSecret missing

5. Registry database credential warning — the DB URI includes a
   password; supply it as a one-off --set flag at preflight time, never
   in a permanent or GitOps-tracked values file (the spec ships as a
   Secret, so a persistent value leaves the password in-cluster
   indefinitely).

6. Advisory by default — on the Helm CLI path, kubectl preflight
   can't block helm install. A fail is a signal to act on manually, not
   an automatic gate.

7. Optional real enforcement (preflight.enforce=true) — full
   coverage: what it does (in-cluster pre-install/pre-upgrade Job that
   genuinely fails the release on fail), its two prerequisites
   (global.replicated.dockerconfigjson for the license-gated runner
   image; the Job's own cluster-scoped read RBAC), how to diagnose a
   blocked install (kubectl logs job/<release>-preflight-check), and how
   to bypass a known false positive (--set preflight.enforce=false).

8. What preflight can't check — installer RBAC rights (no
   SelfSubjectAccessReview-style analyzer; verify with kubectl auth can-i) and CRD collisions with a prior install (no CRD analyzer ships;
   check kubectl get crd | grep toolhive.stacklok.dev by hand).

airgap-install.mdx addition

Short subsection under "Step 5: Install and verify": the default spec runs
entirely offline, so it works unchanged air-gapped. Template the locally
transferred chart directory instead of the oci:// reference. Note that
mirroring the preflight_<os>_<arch>.tar.gz release asset alongside the
chart/image transfer covers the CLI plugin itself if the transfer
workstation needs it.

Style: second person, active voice, no em dashes, sentence-case
headings, tables for structured comparisons, :::note/:::warning
admonitions for the CLI-version guidance and the credential-handling
callout, matching the conventions already used in both target pages.

Context and references

• Upstream implementation: stacklok/stacklok-enterprise-platform#2513
• Upstream RFC: docs/rfcs/replicated-preflights.md (same repo)
• Upstream customer docs this content is sourced from:
  docs/customer/install-helm.md and docs/replicated/troubleshoot.md
  (same repo)
• Replicated's own preflight docs, confirming the Helm CLI path is
  advisory-only and strict: true blocking only applies to Replicated
  native installers (Embedded Cluster/KOTS/kURL):
  docs.replicated.com/vendor/preflight-defining,
  docs.replicated.com/vendor/preflight-running

Use case

As a Stacklok Enterprise Platform customer, I want to catch install-time
misconfigurations (unsupported Kubernetes version, insufficient node
capacity, an unreachable OIDC issuer, a missing signing-key Secret) before
helm install fails partway through, so I can fix problems upfront instead
of debugging a partially-applied release.

Additional context

Scope is documentation only; the feature itself is already implemented and
merged upstream.

[glageju]

Implementation plan

Task 1: Add "Run preflight checks" section to deployment.mdx

• Insert a new ## Run preflight checks section immediately after "What
  the chart includes" and before "Deploy with Helm".
• Subsections: framing / installing the CLI plugin (pinned vs. krew) /
  running against real values / "What it checks" table / registry-database
  credential warning / advisory-by-default / optional
  preflight.enforce=true enforcement / what preflight can't check (RBAC,
  CRD collisions).
• Verify heading hierarchy (## for the section, ### for subsections)
  and no duplicate headings:
  grep -n "^## \|^### " docs/platform/enterprise-platform/deployment.mdx
• Format and lint the file:
  npm run prettier:fix -- docs/platform/enterprise-platform/deployment.mdx
npm run eslint:fix -- docs/platform/enterprise-platform/deployment.mdx
• Commit: "Document preflight checks in platform deployment guide"

Task 2: Add air-gap preflight note to airgap-install.mdx

• Insert a ### Run preflight checks against the mirrored chart
  subsection inside ## Step 5: Install and verify, before the existing
  "failure mode to watch for" paragraph.
• Content: default spec runs fully offline; template the locally
  transferred chart directory instead of oci://; mirror the
  preflight_<os>_<arch>.tar.gz release asset if the transfer workstation
  needs the CLI plugin.
• Verify placement/headings, format, and lint the same way as Task 1.
• Commit: "Document preflight checks for air-gapped installs"

Task 3: Full-site verification

• npm run prettier and npm run eslint across the whole repo; confirm
  the two modified files report clean.
• npm run build; confirm no broken-link errors, especially the
  #3-configure-values, #4-install-the-chart,
  #run-preflight-checks, and #step-1-get-your-license-and-image-list
  anchors referenced across the two pages.
• Re-check whether the pinned preflight CLI version (v0.115.0 at design
  time) still matches
  build/replicated/Taskfile.yml's PREFLIGHT_CLI_VERSION in
  stacklok/stacklok-enterprise-platform, since it may have moved before
  this plan is executed. Update the doc if it has.
• npm run start; manually check both pages render correctly (heading
  levels, code block fencing, no literal escaped backticks) and every new
  internal link resolves.

Global constraints (apply to every task)

• Front matter title/description unchanged on both pages; no new pages.
• Second person, active voice, US English, Oxford commas, straight quotes,
  no em/en dashes.
• ATX-style headings, sentence case, unique within each document.
• Fenced code blocks with declared language, blank lines around them.
• :::type admonitions with blank lines around start/end directives.
• 80-character line wrap (exceptions for links/tables/headings/code
  blocks).
• Run prettier:fix/eslint:fix per file; pre-commit hook may not fire
  in CI or unattended runs.
• npm run build before opening the PR.
• Commit messages: imperative mood, no conventional-commits prefix,
  subject under ~50 characters.