feat(env): tokenize hardcoded dev LAN addresses into cluster-vars (R-ENV-02)

R-ENV-02 promises dev and prod differ ONLY by scoped cluster-vars overrides. In fact
dev LAN addresses were hardcoded into base manifests, so clusters/prod would have come
up ANNOUNCING DEV ADDRESSES (192.168.1.x) on the prod LAN (192.168.2.x).

New cluster-vars knobs (base default = dev literal, per the file's existing convention):
  K3S_API_HOST          platform/cilium/helmrelease.yaml (+ the values.yaml mirror)
  CILIUM_LB_POOL_START  platform-config/cilium/l2-ip-pool.yaml
  CILIUM_LB_POOL_STOP   "
  UNIFI_L4_VIP          apps/vms/unifi/50-service-l4.yaml
  CRAFTY_L4_VIP         platform/crafty/service-l4.yaml
  S3_BACKUP_ENDPOINT    platform/keycloak/postgres-cluster.yaml, apps/wave-0/{nextcloud,
                        semaphore}-db.yaml, and platform/velero/helmrelease.yaml

Also fixes GATEWAY_VIP's base default, which was still the RETIRED libvirt address
10.73.0.240, and adds the GATEWAY_VIP patch that clusters/prod was missing entirely.

clusters/base/apps-vms.yaml gains postBuild.substituteFrom (it was the one consuming
Kustomization without it, so a ${TOKEN} there would have shipped as a literal string).
The envsubst contract is documented there: ${VAR} substitutes and escapes as $${VAR};
$VAR and $(cmd) are left alone; ${ARR[0]} hard-errors. The three UOS_URL expansions in
the unifi cloud-init are escaped accordingly.

PROD ADDRESS PLAN (operator, 2026-08-31):
  nodes .10/.11/.12 · control-plane VIP .9 (Ansible-side) · GATEWAY_VIP .20
  Cilium LB pool .20-.30

CONTAINMENT INVARIANT, now documented at the pool and in the prod overlay: GATEWAY_VIP
MUST equal CILIUM_LB_POOL_START. The shared Gateway pins no address, so Cilium LB-IPAM
gives it the first free address of a matching pool block. An initial prod proposal put
.20 outside a .21-.30 pool; the Gateway would have come up on .21 while split-horizon
coredns-custom kept answering *.home.keithjackson.dev with .20 — an address nothing
announces — blackholing in-cluster OIDC hairpin traffic while reporting healthy. The
pool was widened to .20-.30. The control-plane VIP (.9) stays outside the pool so
kube-vip and LB-IPAM can never contend.

Values prod still cannot know stay INVALID `TBD-PROD-*` placeholders on purpose: base
defaults are dev values, so an omitted patch means prod silently inherits a dev address
— far worse than a loud failed apply.

DEV IS BYTE-IDENTICAL. Verified by kustomize build over 13 paths before/after, then
flux envsubst with the dev cluster-vars values applied to both sides: zero drift. The
only deltas are the intended additive keys in the overlay ConfigMap itself. No
unresolved ${TOKEN} survives. render-golden green (10 goldens); yamllint clean.

Serves: R-ENV-02. Task: T-7.1 (prerequisite). Gate: MERGE GATE: PASS.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

clusters/README.md

@@ -40,6 +40,31 @@ they add no resources of their own and never copy/fork a base manifest. Promotio
 ([`docs/02`](../../home-network-k3s/docs/02-environments-and-provisioning.md)) is a change to the
 prod overlay's variables, nothing else.
 
+### LAN addressing is a knob, not a literal (fixed 2026-08-31)
+
+Until 2026-08-31 the base manifests hardcoded the **dev** LAN: the k3s API host Cilium dials, the
+Cilium LB IP pool range, the pinned crafty/unifi L4 VIPs and the off-cluster S3 backup endpoint. That
+broke R-ENV-02 outright — `clusters/prod` would have rendered dev addresses (192.168.1.x) onto the
+prod LAN (192.168.2.x). They are now the `cluster-vars` "LAN addressing" block
+(`K3S_API_HOST`, `CILIUM_LB_POOL_START`/`_STOP`, `UNIFI_L4_VIP`, `CRAFTY_L4_VIP`,
+`S3_BACKUP_ENDPOINT`, alongside the pre-existing `GATEWAY_VIP`), set explicitly by BOTH overlays.
+
+Two rules when touching that block:
+
+1. **Substitution coverage.** A `${TOKEN}` only resolves in a path whose Flux Kustomization declares
+   `postBuild.substituteFrom: cluster-vars`; anywhere else the literal string `${TOKEN}` ships to the
+   cluster. `apps-vms` was the one path without it and now has it — which means every shell `${...}`
+   in a VM manifest's cloud-init must be escaped `$${...}` (see `clusters/base/apps-vms.yaml` for the
+   full envsubst escape contract).
+2. **`GATEWAY_VIP` must be inside `CILIUM_LB_POOL_START..STOP`,** and in practice equal to START: the
+   `shared` Gateway pins no address, so Cilium LB-IPAM gives it the pool's first free IP while
+   split-horizon CoreDNS answers with `${GATEWAY_VIP}`. A VIP outside the pool blackholes in-cluster
+   hairpin traffic while the Gateway still looks healthy.
+
+Values the operator has not decided are `TBD-PROD-*` placeholders, not guesses: prod inherits the
+DEV base defaults if an overlay op is simply omitted, so an invalid value that fails loudly is
+strictly safer than a plausible one that quietly comes up on the wrong network.
+
 ## How Flux is pointed at an environment
 
 `flux bootstrap` (run by WS-INFRA in Phase 1) targets one environment's path per cluster: