fix(renovate): the config was INVALID, so the first manual run errored out

The operator ran the Renovate workflow manually and it failed. The cause is not the workflow: renovate.json was never a valid Renovate config. It carried five pseudo-comment keys (_comment, _kubernetes_comment, _unmanageable_comment, _ignorePaths_comment, _docker_comment) because JSON has no comments, and Renovate REJECTS unknown top-level options. Proven with the official validator: ERROR: Found errors in configuration Invalid configuration option: _comment Invalid configuration option: _docker_comment Invalid configuration option: _ignorePaths_comment Invalid configuration option: _kubernetes_comment Invalid configuration option: _unmanageable_comment This is the SECOND independent reason Renovate never worked, on top of PR #77's cron firing outside renovate.json's own schedule window. Either alone was enough to produce "nothing ever happens"; #73 shipped both. Converted renovate.json -> renovate.json5. JSON5 permits real // comments and Renovate discovers renovate.json5 natively; nothing in .gitea/ or ci/ pins the old filename and no RENOVATE_CONFIG_FILE is set. Every word of the original rationale is preserved as positioned comments (74 comment lines) rather than flattened into a description string. Verified the conversion dropped nothing: 18 non-comment keys before and after, no missing/extra keys, no changed values, docker: {enabled: true} still present. The validator now returns "Config validated successfully". DISPROVED while here: `enabledManagers` containing bare `regex` was suspected of needing to be `custom.regex` (which would silently disable every inline `# renovate:` marker). The validator accepts `regex`; unfounded, unchanged. Renovate has still never completed a run -- this fixes one of two blockers and nothing in the gate catches an invalid config. See the handoff. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Merge pull request 'fix(conformance): one regex made the merge gate take 28 minutes instead of 2' (#76 ) from fix/ha-check-catastrophic-regex into main
2026-10-18 03:10:25 -05:00 · 2026-10-18 07:51:51 +00:00 · 2026-10-18 07:40:20 +00:00 · 2026-10-18 02:38:23 -05:00 · 2026-10-18 01:43:43 -05:00 · 2026-10-18 06:28:30 +00:00
22 changed files with 2062 additions and 150 deletions
@@ -445,8 +445,21 @@ join = re.search(r"--server https://\{\{\s*k3s_api_host", K3S_TEXT)
 check(join is not None,
      "roles/k3s_server does not join secondaries with `--server https://{{ k3s_api_host }}` "
      "— without a join target the servers are separate single-node clusters")
-join_when = re.search(r"--server https://.*?\n(?:.*\n){0,10}?\s*when:\s*k3s_server_mode\s*==\s*'secondary'",
-                      K3S_TEXT, re.S)
+# LINE-BOUNDED ON PURPOSE -- DO NOT "SIMPLIFY" BACK TO `.*` + re.S.
+# This was `--server https://.*?\n(?:.*\n){0,10}?\s*when:...` with re.S, which made every `.`
+# match newlines too. That is nested unbounded repetition (a `{0,10}` of a quantifier that can each
+# swallow the whole document), so a FAILED or late match backtracks exponentially. It cost
+# **19m54s of CPU in CI** (measured 2026-10-18 via `docker top` on the live job container) and made
+# the whole merge gate take ~28 minutes instead of ~2 on any change touching `infra/**` -- because
+# `ci/touched-requirements.sh` maps `infra/*` to R-ENV-01, which pulls in this whole-repo check.
+# It was latent for as long as the regex existed and only crossed the threshold when
+# roles/k3s_server grew by ~100 lines (the kubelet graceful-shutdown config, PR #71): K3S_TEXT is
+# every *.yml in that role concatenated, so the role growing is the input growing.
+# `[^\n]*` cannot cross a line, so the `{0,10}` is a genuine ten-line window with nothing to
+# backtrack into. Measured on the same input: 0.2 ms, same verdict (match found).
+join_when = re.search(
+    r"--server https://[^\n]*\n(?:[^\n]*\n){0,10}?[ \t]*when:[ \t]*k3s_server_mode[ \t]*==[ \t]*'secondary'",
+    K3S_TEXT)
 check(join_when is not None,
      "the join install task is not gated on k3s_server_mode == 'secondary' — the founder "
      "would also try to join itself")
@@ -185,6 +185,55 @@ Measured against the live cluster and nodes, read-only, on 2026-10-17.
 - **`renovate.json` parses** as valid JSON after my edits (`json.load`).
 - **kured is not installed** and the string `kured` appears nowhere in the repo — greenfield.

+### CORRECTION 2026-10-18 — the first real run FAILED, and the sentinel design was wrong
+
+`ansible-playbook playbooks/unattended-upgrades.yml -e k3s_hosts=k3s_prod` failed on all three
+nodes at the package task:
+
+```
+fatal: [k3s-prod-1]: FAILED! => "No package matching 'update-notifier-common' is available"
+```
+
+**`update-notifier-common` is an UBUNTU package and does not exist in Debian.** Measured on trixie:
+`apt-cache policy update-notifier-common` → `Candidate: (none)`. The original entry asserted this
+package "owns the hook that creates /var/run/reboot-required" — true on Ubuntu, false here, and the
+role could never have worked. This was the exact risk the first version of this entry flagged ("the
+`find` patterns are a guess at which package ships what") landing in a worse place than predicted:
+not a wrong glob, a nonexistent package.
+
+Three further measurements settled what to do instead:
+
+* `/usr/share/update-notifier/notify-reboot-required` is **absent**.
+* **No `linux-image-*` postinst references `notify-reboot-required`** — invoking it is an Ubuntu
+  patch, so merely placing a script at that path would never be called.
+* No hook under `/etc/apt/apt.conf.d` or `/etc/kernel/` mentions `reboot-required`.
+
+So Debian trixie has **no stock mechanism at all**, and the role now ships the writer itself:
+`/usr/local/sbin/k3s-notify-reboot-required` (compares the running kernel against the newest
+installed via `linux-version`, from `linux-base`, which every `linux-image` depends on — measured
+`linux-base 4.12.1` present) plus a `DPkg::Post-Invoke` hook at
+`/etc/apt/apt.conf.d/99-k3s-reboot-required`. `/run` is a tmpfs (measured), so the sentinel
+self-clears on boot and needs no cleanup task.
+
+The verify assert changed shape too: it was a `find` glob over `/etc/kernel/postinst.d` and
+`/etc/apt/apt.conf.d` for `*update-notifier*` / `*unattended-upgrades*`. That glob was **weaker
+than it looked** — it would have matched Debian's own `unattended-upgrades` apt conffile and
+reported "sentinel writer present" while no writer existed. It now stats the two exact paths this
+role owns and requires the script to be executable.
+
+**Newly verified (this correction):** the sentinel script was executed on prod-1 as the
+unprivileged `k3s` user under `sh -x`. It resolved `running=7.1.8+deb13-amd64`,
+`newest=7.1.8+deb13-amd64`, took the equal branch, exited 0 and wrote nothing — correct, since the
+running kernel *is* the newest. `sh -n` and `bash -n` clean.
+
+**Still NOT verified after this correction:** the *writing* half. Because running == newest on all
+three nodes, the `touch` path has never executed, so I have not seen the sentinel actually created,
+nor seen kured react to it. The honest test is the operator's next kernel upgrade. Also unverified:
+whether a `DPkg::Post-Invoke` hook fires in the `unattended-upgrades` code path specifically (it
+runs dpkg, so it should, but that is inference) — and whether `linux-version sort --reverse` orders
+a mixed backports/stable kernel set the way I assume when a 6.12 and a 7.1 are both installed. It
+produced the right answer with the current set; a future set could differ.
+
 ## What I did NOT verify

 The honest list. Most of this needs an actual upgrade cycle, which I did not and could not run.
@@ -0,0 +1,106 @@
+---
+date: 2026-10-17
+branch: feat/graceful-cluster-shutdown
+title: "Graceful node shutdown was never configured, and scaling a StatefulSet deleted its PVC"
+---
+
+## What changed
+
+All three nodes had to be powered off to move them onto a UPS. There was **no procedure for it**:
+`infra/cluster.sh stop` is `virsh`-based and only ever applied to the decommissioned dev cluster, so
+the whole sequence was improvised live. Two defects came out of doing it.
+
+**1. Kubelet graceful node shutdown was unconfigured on every prod node.** No `shutdownGracePeriod`
+anywhere in `infra/ansible/`, so `shutdown -h` stopped k3s, containerd went with it, and every pod
+was SIGKILLed where it stood — 9 CloudNativePG instances mid-checkpoint, the UniFi VM, and 25
+attached Longhorn volumes. `roles/k3s_server` now writes `kubelet-arg` into
+`/etc/rancher/k3s/config.yaml` with `shutdown-grace-period=90s` and
+`shutdown-grace-period-critical-pods=20s`.
+
+The half that is easy to miss and silently defeats the other half: **graceful node shutdown is
+enforced by logind, not by the kubelet.** The kubelet holds an inhibitor *delay* lock and systemd
+waits at most `InhibitDelayMaxSec` — **default 5 seconds** — before proceeding regardless. A grace
+period above that cap is truncated with no error, so the feature looks configured and still
+hard-kills pods. The role now ships a `logind.conf.d` drop-in setting it to 120, and **asserts**
+`k3s_logind_inhibit_delay_max_sec >= k3s_kubelet_shutdown_grace_period` rather than documenting the
+relationship, because the failure is invisible.
+
+**2. Scaling a StatefulSet to 0 DELETED its PVC and Longhorn volume.** `monitoring/loki` carries
+`persistentVolumeClaimRetentionPolicy: {whenDeleted: Delete, whenScaled: Delete}`, so the quiesce's
+`scale --replicas=0` destroyed `storage-loki-0` outright. Loki stores with `type: filesystem`, so
+that PVC was the only copy of its log data. This is the defect in this change set that actually
+destroyed something, and it was mine.
+
+New `infra/maintenance/quiesce.sh` (`quiesce` | `resume` | `status`) encodes the sequence that
+worked, and **refuses to scale any StatefulSet whose `whenScaled` is `Delete`** — it leaves it
+running, accepts that its volume hard-detaches at poweroff, and prints which volumes to expect
+`degraded`. A rebuild is a vastly better outcome than a deletion. Workload discovery is computed
+from the live cluster (every Deployment/StatefulSet whose pods mount a PVC, Longhorn or TrueNAS NFS)
+rather than hardcoded, so a newly onboarded service is covered without anyone remembering to add it.
+
+`runbooks/cluster-maintenance-shutdown.md` (new, registered in `runbooks/kustomization.yaml`) is the
+operator page: shutdown order, the TrueNAS-after-nodes constraint, power-on order, the
+un-hibernate-Postgres step Flux will not do for you, and a "what looks broken but is fine" section
+separating the `4/19`-Kustomizations-Ready cascade, the degraded-and-rebuilding volume and the
+self-recovering `keycloak-operator` from the one thing that genuinely needs a human (a stuck
+`oauth2-proxy` replica).
+
+## What I verified
+
+* **Graceful shutdown was genuinely absent**, not merely undocumented: `grep -rn
+  'shutdownGracePeriod|graceful-node-shutdown'` over `infra/ansible/` returns nothing, and no
+  `logind` or `InhibitDelay` setting exists anywhere in the tree.
+* **The whole shutdown/restart cycle was executed end to end on prod 2026-10-17** and the cluster
+  came back: 3/3 nodes Ready with etcd `healthz` ok, 19/19 Flux Kustomizations Ready,
+  `platform-config`'s `lastAppliedRevision` equal to the GitRepository artifact revision, all 3
+  CNPG clusters `healthy` with primaries elected, the UniFi VM `Running`, PiHole resolving
+  (`home.keithjackson.dev` → `192.168.2.20` via `192.168.2.23`), and the Gateway serving
+  `200/200/401` for apex/gitea/plex.
+* **The PVC-deletion mechanism is confirmed, not inferred:** `kubectl get sts loki -o
+  jsonpath={.spec.persistentVolumeClaimRetentionPolicy}` returns
+  `{"whenDeleted":"Delete","whenScaled":"Delete"}`, the PVC was `NotFound` after the cycle, and the
+  Longhorn volume count had gone 25 → 24.
+* **The damage was repaired and verified:** `scale sts loki --replicas=1` (restoring the replica
+  count the chart declares) recreated `storage-loki-0` as a fresh 50Gi Bound PVC, `loki-0` reached
+  `2/2 Running`, and the volume count returned to 25.
+* **The guard works against the live cluster**, tested both ways: `sts_deletes_pvc_on_scale
+  monitoring loki` returns true (would be skipped) and `pihole pihole` returns false (safe to
+  scale).
+* **The script's read-only paths run clean on prod:** `status` reports correctly, and the discovery
+  function returns the 13 workloads currently holding a PVC.
+* `bash -n` clean; the two edited Ansible YAML files parse.
+
+## What I did NOT verify
+
+* **The kubelet change has NEVER BEEN APPLIED OR TESTED.** This is the significant gap. I did not
+  run the role, did not restart k3s, and have **not** observed a node actually drain on
+  `shutdown -h`. Everything about it is reasoning from kubelet/systemd semantics plus the measured
+  absence of the setting. Applying it needs a **rolling** k3s restart (`serial: 1` — kube-vip keeps
+  the API up, etcd holds at 2/3), which is an operator action (CLAUDE.md §5). **Verify by draining
+  one node for real:** apply, then `shutdown -h now` on a single node and watch whether pods
+  terminate gracefully instead of vanishing.
+* **Whether 90s/20s are the right numbers.** Chosen to comfortably cover a Postgres fast shutdown
+  and a Longhorn flush; not measured against either. The budget is spent on every reboot, so if a
+  node takes noticeably longer to go down, this is why.
+* **Whether k3s accepts `kubelet-arg` in `config.yaml` as written.** The file already carries
+  `kube-apiserver-arg` as a list and `kubelet-arg` is the documented sibling, but I did not render
+  or apply it, so a typo would surface only at k3s restart — and a bad `config.yaml` is exactly the
+  kind of thing that makes k3s fail to come up. **Review this one before applying.**
+* **The `assert` task's `regex_replace` on the grace period** assumes a plain `90s`-style value; a
+  value expressed as `1m30s` would parse to the nonsense integer `130`. Fine for the committed
+  defaults, wrong if someone writes a compound duration.
+* **`resume`'s Flux-reconcile wait has never run**, and neither has `quiesce` as a script — the
+  2026-10-17 cycle was done with the equivalent commands by hand, so the script encodes a sequence
+  that worked but has not itself been executed end to end. Only `status` and the discovery and guard
+  functions have run.
+* **Loki's lost log window is gone for good.** Up to 72h of logs (its `retention_period`), destroyed
+  by my scale-down. Nothing recovers it; Velero's schedules cover the namespace but the PVC was
+  deleted, not corrupted, and I did not attempt a restore because the data self-expires anyway.
+* **No other `whenScaled: Delete` StatefulSet was audited.** The guard now catches them generically,
+  but I did not enumerate which other workloads carry the policy, so I cannot say loki was the only
+  one at risk. The runbook gives the one-liner to list them.
+* **TrueNAS and the router are entirely outside this change.** TrueNAS is not in the Ansible
+  inventory and refuses SSH, so its shutdown stays a web-UI step with no automation and no check.
+* **No runtime conformance.** `vars.CLUSTER_AVAILABLE` is still unset, so CI proves the L0/L1
+  offline subset only.
+* I did not re-measure branch protection or runner state (CLAUDE.md §2b).
@@ -0,0 +1,311 @@
+---
+date: 2026-10-17
+branch: feat/keycloak-passkeys
+title: Passkeys declared for the homelab realm — and the realm import will not apply them
+---
+
+## What changed
+
+`platform/keycloak/keycloak-realm-import.yaml` now declares passkey (WebAuthn Passwordless)
+login for the `homelab` realm, in two parts:
+
+1. **The WebAuthn Passwordless policy.** Ten `webAuthnPolicyPasswordless*` fields on the realm:
+   RP ID `${BASE_DOMAIN}`, RP entity name `Homelab SSO`, signature algorithms `[ES256, RS256]`,
+   `requireResidentKey: "Yes"`, `userVerificationRequirement: required`,
+   `authenticatorAttachment: "not specified"`, `attestationConveyancePreference: none`,
+   `acceptableAaguids: []`, `createTimeout: 300`, `avoidSameAuthenticatorRegister: true`.
+   Deliberately the **passwordless** family only; the two-factor `webAuthnPolicy*` family is left
+   at Keycloak's defaults because nothing in this realm uses `webauthn-authenticator`.
+
+2. **The browser flow.** `browser-mfa` keeps its alias and stays bound as `browserFlow`; its
+   interior is restructured so a passkey is an **ALTERNATIVE** beside the password form:
+
+   ```
+   browser-mfa                            (top level, unchanged)
+     browser-mfa-forms                    ALTERNATIVE
+       auth-username-form                   REQUIRED      <- was auth-username-password-form
+       browser-mfa-passkey-or-password      REQUIRED      <- NEW sub-flow
+         webauthn-authenticator-passwordless  ALTERNATIVE <- NEW: the passkey
+         browser-mfa-password-and-otp         ALTERNATIVE <- NEW sub-flow
+           auth-password-form                   REQUIRED  <- was half of the combined form
+           browser-mfa-conditional-otp          CONDITIONAL (unchanged, relocated intact)
+   ```
+
+The design decisions, with their reasoning, are written into the manifest comments in this repo's
+usual density. The ones that matter:
+
+* **Additive, not replacing. Enrolment optional, not forced.** This IdP gates Grafana, Gitea,
+  Nextcloud, Headlamp, Semaphore, PiHole, Crafty, the \*arr stack *and* `kubectl` via the
+  `kubernetes` OIDC client. A mandatory passkey flow that misfires is a total lock-out from the
+  platform and the cluster API at once, leaving only the Keycloak bootstrap admin and the
+  break-glass cert kubeconfig. The gain from forcing it (one human stops typing a password) does
+  not price that risk.
+* **No `requiredActions` block was added, on purpose.** Declaring one would have been the obvious
+  way to add `webauthn-register-passwordless`, and it would have been actively dangerous — see
+  "What I verified".
+* **RP ID is `${BASE_DOMAIN}`, not `keycloak.${BASE_DOMAIN}`.** A passkey's RP ID is fixed at
+  enrolment and can never be re-keyed, so it must not be bound to a name that can move. This realm
+  already declares an `auth.${BASE_DOMAIN}` redirect URI, and this repo already owns a reconciler
+  built because a hostname move silently failed to reach the realm. Residual risk, unavoidable:
+  changing `BASE_DOMAIN` itself invalidates every enrolled passkey.
+* **A passkey login is not also asked for TOTP.** `browser-mfa-conditional-otp` hangs off the
+  password branch only. The justification is `userVerificationRequirement: required` — the
+  ceremony already proves possession plus a verified human, phishing-resistantly and origin-bound.
+  Stacking a replayable shared secret on top of that buys friction. The manifest names the exact
+  one-line edit to reverse this decision.
+* **Login becomes two screens** (username, then password) for every user, passkey or not, because
+  the server must know who is logging in before it can decide whether a passkey exists. Accepted
+  cost; it is the enabling change.
+* **Usernameless login deliberately not used**, although Keycloak 26.0.6 supports it — see "What I
+  verified" for the measured reason it would have made every login open on a passkey prompt.
+
+`platform/keycloak/README.md` gains a `## Passkeys` section: the decision table, the fact that
+this does not reach the live realm, the two operator paths that would apply it, and the four-step
+browser verification nobody has run.
+
+No secret, key, credential or AAGUID was minted or committed. No file under `clusters/**`,
+`conformance/**`, `ci/**`, `platform/kyverno/**`, `**/rbac.yaml` or `**/*.sops.yaml` was touched,
+so this should not trip `ci/approval-policy.sh`'s sensitive-path review requirement.
+
+## What I verified
+
+**The live realm import has already completed and will never re-run.** Measured on prod,
+2026-10-17:
+
+```
+$ kubectl --context k3s-prod -n keycloak get keycloakrealmimport homelab -o jsonpath='{.status}'
+{"conditions":[{"message":"","status":"True","type":"Done"},
+               {"message":"","status":"False","type":"Started"},
+               {"message":"","status":"False","type":"HasErrors"}]}
+```
+
+`Done=True` / `Started=False`, exactly the one-shot state `platform/keycloak/README.md` already
+documents for client secrets and client URLs. **So the change in this PR has zero effect on how
+anyone logs in today**, and the client-secret/client-URL reconciler does not and cannot close the
+gap: its hard endpoint allow-list makes `/authentication` unreachable by design, and realm-level
+policy fields are not client fields.
+
+**The CRD accepts every field I used.** Measured against the live CRD (not the upstream docs):
+`kubectl --context k3s-prod get crd keycloakrealmimports.k8s.keycloak.org` lists all twelve
+`webAuthnPolicyPasswordless*` properties with the types I wrote (`RequireResidentKey`,
+`RpEntityName`, `RpId`, `UserVerificationRequirement`, `AttestationConveyancePreference`,
+`AuthenticatorAttachment` as `string`; `SignatureAlgorithms`, `AcceptableAaguids`, `ExtraOrigins`
+as `array/string`; `CreateTimeout` as `integer`; `AvoidSameAuthenticatorRegister` as `boolean`),
+plus `authenticationFlows`, `authenticatorConfig` and `requiredActions`. The `spec.realm` schema
+has **no** `x-kubernetes-preserve-unknown-fields`, so a misspelled field would have been pruned
+silently rather than rejected — which is why this was checked rather than assumed.
+
+**Running Keycloak is 26.0.6.** `quay.io/keycloak/keycloak:26.0.6` on `keycloak-0`/`keycloak-1`,
+operator `quay.io/keycloak/keycloak-operator:26.0.6`. Every source claim below is read from the
+`26.0.6` tag, not from memory or from docs.
+
+**Every provider ID is quoted from upstream source, not guessed.**
+
+| String I used | Where it is defined at tag 26.0.6 |
+|---|---|
+| `webauthn-authenticator-passwordless` | `WebAuthnPasswordlessAuthenticatorFactory.PROVIDER_ID`, display "WebAuthn Passwordless Authenticator" |
+| `auth-username-form` | `UsernameFormFactory.PROVIDER_ID`, display "Username Form" |
+| `auth-password-form` | `PasswordFormFactory.PROVIDER_ID`, display "Password Form" |
+| `webauthn-register-passwordless` | `WebAuthnPasswordlessRegisterFactory.PROVIDER_ID` (referenced in comments only) |
+
+**`requiredActions` is REPLACE, not merge — measured, and it is why I did not declare one.**
+`model/storage-private/.../DefaultExportImportManager.java` lines 327-338:
+
+```java
+if (rep.getRequiredActions() != null) {
+    for (RequiredActionProviderRepresentation action : rep.getRequiredActions()) { ... }
+    DefaultRequiredActions.addDeleteAccountAction(newRealm);
+} else {
+    DefaultRequiredActions.addActions(newRealm);
+}
+```
+
+Declaring one required action therefore skips the entire default set. `RealmManager` is no
+backstop: `setupRequiredActions` is `if (realm.getRequiredActionProvidersStream().count() == 0)`,
+and the count is already non-zero by then (`RepresentationToModel.importRealm` runs at
+`RealmManager.java:585`, the backstop at `:612`). A realm built that way would have had the passkey
+action plus `delete_account` and nothing else — **no `CONFIGURE_TOTP`**, which would leave
+`auth-otp-form` demanding a TOTP that no platform-admin could ever enrol: a hard lock-out
+delivered by a change whose purpose was to *add* a login method.
+
+**And declaring it would have bought nothing.** `DefaultRequiredActions.addWebAuthnPasswordlessRegisterAction`
+registers `webauthn-register-passwordless` with `setEnabled(true)`, `setDefaultAction(false)`,
+priority 80, gated on `Profile.Feature.WEB_AUTHN` — which is `Type.DEFAULT` in
+`common/.../Profile.java:74`, i.e. on unless explicitly disabled. `enabled=true` /
+`defaultAction=false` *is* the additive-and-optional posture this change wants.
+
+**`authenticationFlows` has the opposite semantics, which is why declaring flows is safe.**
+`importAuthenticationFlows` adds the declared flows, then backfills each unbound binding
+(browser, registration, direct grant, reset credentials, client auth, first broker login, docker
+auth) from the built-in defaults individually (`DefaultExportImportManager.java` ~1320-1410).
+
+**The graceful degradation to password is measured from the flow engine, not assumed.** For a user
+with no passkey: `WebAuthnPasswordlessAuthenticator.requiresUser()` returns `false`, so
+`DefaultAuthenticationFlow.processSingleFlowExecutionModel` takes the `else` branch (`daf:456-462`),
+whose four conditions all hold — a user is set (from `auth-username-form`), `configuredFor` is
+false, `WebAuthnPasswordlessAuthenticatorFactory.isUserSetupAllowed()` is `false`, and
+`WebAuthnAuthenticator implements Authenticator, CredentialValidator<...>` — so it raises
+`CREDENTIAL_SETUP_REQUIRED`. The ALTERNATIVE loop (`daf:289-302`) catches exactly that, marks the
+execution `ATTEMPTED` and proceeds to the next alternative, with the upstream comment *"the user,
+since he has alternatives, should be able to go to another alternative and continue"*. Hence: no
+passkey, no passkey screen, straight to the password form.
+
+**Why usernameless was rejected, measured.** The `configuredFor` guard sits inside the
+`requiresUser()` branch. With `requiresUser()` false and no user yet in context, that guard is
+skipped and the engine just calls `authenticate(context)` — so a passkey execution placed before
+the username form is offered to *everyone*, including users who will never own one.
+
+**The policy sentinels are read from the shipped code, and one of my initial assumptions was
+wrong.** `Constants.DEFAULT_WEBAUTHN_POLICY_NOT_SPECIFIED = "not specified"` is the
+realm-representation sentinel — but `WebAuthnConstants.OPTION_NOT_SPECIFIED = ""` (empty string) is
+the WebAuthn-API-level one. I checked both because they disagree. The login theme's
+`webauthnRegister.js` at 26.0.6 settles the behaviour:
+
+```js
+if (input.requireResidentKey !== 'not specified') {
+    if (input.requireResidentKey === 'Yes') { authenticatorSelection.requireResidentKey = true; }
+    else { authenticatorSelection.requireResidentKey = false; }
+}
+...
+if (input.createTimeout !== 0) { publicKey.timeout = input.createTimeout * 1000; }
+rp: {id: input.rpId, name: input.rpEntityName}
+```
+
+So `"Yes"` is a literal string compare (any other non-sentinel value means *false*), `"not
+specified"` is compared literally for four fields, and `createTimeout` is **seconds** with `0`
+meaning "send no timeout". It also shows 26.0.6 emits only the legacy `requireResidentKey` member,
+never `residentKey: "required"` — the client maps that per WebAuthn L2, but the policy cannot
+express `residentKey: "preferred"` at all.
+
+`[ES256, RS256]` is exactly `WebAuthnPolicy.DEFAULT_POLICY` /
+`Constants.DEFAULT_WEBAUTHN_POLICY_SIGNATURE_ALGORITHMS` — declared explicitly, not changed.
+`getWebAuthnPolicyPasswordless` was read field by field to confirm `[]` for `acceptableAaguids`
+means "no restriction" and that `RpEntityName` must be non-empty or the **update** path
+(`DefaultExportImportManager.java:842`) drops the whole policy silently.
+
+**The manifest parses and renders.** `yaml.safe_load` round-trips the file and the flow graph reads
+back exactly as designed (five flows, the executions and priorities above, `browserFlow:
+browser-mfa`, `requiredActions` absent). `python3 ci/render-keycloak-client-urls.py --check` →
+`client-urls.yaml is in sync`, rc 0 (no client URL changed, so no regeneration was needed).
+`yamllint -c ci/yamllint.yaml platform/keycloak/keycloak-realm-import.yaml` → rc 0; no line exceeds
+the 160-column ceiling.
+
+**`browser-mfa` keeps its alias deliberately.** `conformance/tests/l2-behavioral/keycloak-config-as-code`
+asserts `kubectl get keycloakrealmimport homelab -o jsonpath={.spec.realm.browserFlow} | grep -q
+'browser-mfa'`. Renaming the top-level flow would have failed that test.
+
+**Envsubst safety.** `platform-config`'s Flux Kustomization declares
+`postBuild.substituteFrom: cluster-vars` (`clusters/base/platform-config.yaml:26-29`), so this file
+is substituted. The only brace token I added is `${BASE_DOMAIN}`, which is declared at
+`clusters/base/cluster-vars.yaml:42` (`home.keithjackson.dev`). Every comment I wrote avoids braces
+entirely — the RP-ID discussion says `keycloak.<BASE_DOMAIN>` with angle brackets precisely so an
+unparseable token cannot fail the whole Kustomization.
+
+**Gate result: rc 3, zero failures, `gitea-settings` the only stage the gate counts as not-run** —
+the documented honest best local outcome. Run in the pinned toolbox from this worktree with all
+three §3 workarounds (`DEV_KUBECONFIG=/dev/null`, plus an `ENGINE` shim bind-mounting the main
+checkout's `.git` and the sibling spec repo with `SPEC_REPO=/home-network-k3s`):
+
+```
+[ ok ] stage spec-immutability: pass      <- NOT skipped; both shim mounts worked, R-TEST-06 covered
+[ ok ] stage decisions-log: pass          <- archive frozen, 48 entries well-formed
+[ ok ] stage lint: pass
+[ ok ] stage l0: pass                     <- incl. flux-postbuild-substitution + keycloak-client-secret-reconciler
+[ ok ] stage render-golden: pass
+[ ok ] stage l1: pass
+[ ok ] stage approval-policy: pass        <- no sensitive path touched, so no non-author review needed
+[skip] stage gitea-settings: SKIPPED      <- needs SETTINGS_API_TOKEN, CI-only; expected
+[skip] stage conformance: SKIPPED         <- cluster-gated L2/L3; expected
+MERGE GATE: UNDETERMINED — Stages that did not run: gitea-settings
+```
+
+No lint finding and no check failure names either file I changed. Touched requirements resolved to
+`R-IDP-01 R-IDP-02 R-IDP-03 R-IDP-04 R-IDP-05 R-IDP-06`; coverage 51/51, 0 gaps.
+
+**A note on how that number was obtained, because the first attempt was worthless.** My first gate
+run returned the same rc 3 and the same seven passes — against a tree that did not contain this
+change at all. The gate's `tracked_files()` reads **git**, and my edits were still uncommitted, so
+every stage gated `origin/main`. The tell was in the log and I nearly missed it: the
+touched-requirement subset reported UNDETERMINED with *"check out the feature branch you mean to
+gate (not the base branch)"*, and `decisions-log` counted **47** entries rather than 48. **A green
+gate run on an uncommitted worktree is a gate run on the base branch.** The numbers above are from
+the second run, after committing and rebasing.
+
+**The base moved under me mid-run.** `origin/main` advanced from `9a41a8e` to `1a0b208` (PR #70,
+oauth2-proxy OIDC startup race) while I was working. This branch is rebased onto `1a0b208`, so the
+gate above ran on the base CI will actually merge into. The rebase was clean — PR #70 touched
+`platform/oauth2-proxy/helmrelease.yaml` and its own decisions entry, disjoint from these files.
+
+## What I did NOT verify
+
+**This change is unapplied. It changes nothing about the live realm, and I did not attempt to make
+it.** `Done=True` / `Started=False` was measured, not inferred, and I ran no mutating `kubectl`,
+no `flux reconcile`, no admin-API call and no `kcadm`. Whether the operator's eventual
+admin-console reconstruction of this flow matches what is declared here is, by construction,
+unverifiable from git.
+
+**I never enrolled a passkey and never pointed a browser at any of this.** Nothing here has been
+exercised by a real WebAuthn ceremony on any device. Specifically unverified:
+
+* **That the RP ID works.** `home.keithjackson.dev` is a registrable-domain suffix of
+  `keycloak.home.keithjackson.dev`, so it *should* satisfy the browser's check — but I verified
+  that by reading the WebAuthn rule, not by watching a browser accept it. A wrong RP ID fails
+  **silently, in the browser, before Keycloak is involved**, with no server-side log line. If
+  enrolment produces no OS prompt and no error, this is the first suspect.
+* **That `"not specified"` is the right literal for `authenticatorAttachment` in a realm import.**
+  I traced it to `Constants.DEFAULT_WEBAUTHN_POLICY_NOT_SPECIFIED` and to the theme's string
+  compare, but I have not seen a realm import accept it. Omitting the field would default to the
+  same value; if an import ever rejects the literal, drop the line.
+* **That `createTimeout: 300` behaves.** Seconds-vs-milliseconds is read from the theme JS. The
+  claim that 300 is long enough for the cross-device QR/hybrid flow, and that Chrome clamps rather
+  than rejects it, is reasoning about browser behaviour, not a measurement.
+* **Whether a passkey user can still reach the password form.** I argued it from
+  `createAuthenticationSelectionList` producing a "Try another way" option, and I noted that for a
+  user holding both credentials the *first* screen is chosen by the user's own credential ordering
+  rather than by my priorities. Neither was observed.
+* **The two-screen login regression for ordinary users.** `auth-username-form` +
+  `auth-password-form` replacing `auth-username-password-form` is a visible change for every user
+  including non-passkey family accounts, and nobody has logged in through it.
+* **That conditional OTP for platform-admins still fires on the password branch.** The sub-flow and
+  its `conditional-otp-platform-admin` config are byte-identical and merely relocated one level
+  deeper, but "identical YAML" is not "still enforced at runtime". This is the highest-value
+  regression check and it is untested. The previous breakage of this exact step
+  (`condUserRole` vs a non-existent property key) 403'd every platform-admin login.
+* **That a platform-admin authenticating by passkey is not challenged for TOTP.** That is the
+  intended behaviour of the shape I wrote; it is unobserved, and it is also a deliberate
+  relaxation of R-IDP-04 as previously implemented, which the operator may want to reverse.
+
+**Whether the realm import reconciles into an existing realm: measured as NO for the completed
+one-shot, but I did not test a re-import.** I did not delete and recreate the
+`KeycloakRealmImport`, so I cannot say what a re-run would do to the existing `homelab` realm —
+whether it would merge the new policy and flows, duplicate flow aliases, or fail. The 2026-09-06
+total SSO outage documented in `platform/keycloak/README.md` is the reason I did not experiment.
+**Treat the re-import path in the README as untested advice, not a runbook.**
+
+**Nothing was proved about the live realm's current state.** I did not read the realm's existing
+required actions, its existing WebAuthn policies, or its live flow executions — doing so needs the
+admin credential and I did not decrypt or use it. So I cannot confirm that the live realm's
+required-action set actually contains `webauthn-register-passwordless` today; I can only show that
+Keycloak 26.0.6's defaults register it and that this repo's import never declared any required
+actions to suppress them. **That inference has not been checked against the realm.**
+
+**L2/L3 conformance did not run** (no cluster from the gate container; `vars.CLUSTER_AVAILABLE` is
+unset in CI anyway), so the existing `keycloak-config-as-code` behavioural test did not re-execute
+against this change. I reasoned about its assertion by reading it.
+
+**No new conformance test was added.** Nothing in `conformance/` asserts the passkey policy or the
+new flow shape, so a future edit can silently remove either and no gate stage will notice. That is
+a real gap this PR leaves open; closing it would touch `conformance/**`, which is a sensitive path
+needing non-author review.
+
+**The quoted gate run predates this file's own gate-result paragraph.** It gated commit `207f5db`;
+the gate numbers and the rebase note above were then written into this entry, so the pushed tree
+differs from the gated one by this handoff's prose only — no manifest, no check, no generated file.
+`decisions-log` is the only stage that reads this file, and it validates structure (frontmatter,
+the three headings, non-stub bodies), which is unchanged. I did not re-run the full gate for a
+prose edit; CI will gate the pushed commit.
+
+**`gitea-settings` did not run locally** — it needs `SETTINGS_API_TOKEN`, which exists only in CI.
+I did not re-measure branch protection, the runner, or `required_approvals` against the Gitea API
+this session; the claims in `CLAUDE.md` §2 are taken on trust here and are explicitly flagged there
+as needing re-measurement.
@@ -0,0 +1,108 @@
+---
+date: 2026-10-18
+branch: fix/coredns-ha
+title: "coredns ran at one replica, so any node drain was a cluster-wide DNS outage"
+---
+
+## What changed
+
+**MEASURED on prod 2026-10-18: `kube-system/coredns` had `replicas: 1`.** In-cluster DNS was a
+single pod on a single node, so draining or rebooting that node was a **cluster-wide in-cluster DNS
+outage** until the pod rescheduled and became ready — every Service lookup, every CNPG replica
+finding its primary, every operator addressing the API by name. It was invisible because `1/1
+Ready` looks perfectly healthy.
+
+It also became urgent rather than latent: the scheduled reboot automation on
+`feat/automated-upgrades` drains and reboots one node at a time, unattended, overnight — turning a
+single point of failure into a recurring one.
+
+New `platform/coredns/hpa.yaml`: a `HorizontalPodAutoscaler` on the coredns Deployment with
+`minReplicas: 2`, `maxReplicas: 3`, registered in the existing `platform/coredns/kustomization.yaml`
+alongside the split-horizon ConfigMap already there.
+
+**Why an HPA and not `replicas: 2` — this is the whole decision.** k3s owns the coredns Deployment
+and we cannot durably edit it: it is applied by k3s's own deploy controller from a bundled manifest
+(`AddOn/coredns`, source `/data/k3s/server/manifests/coredns.yaml`, `managedFields` managers
+`deploy@k3s-prod-1` and `k3s`, plus an `objectset.rio.cattle.io/hash` label). k3s re-stages its
+bundled manifests on startup, so a `replicas: 2` written there — or a `kubectl scale` — is reverted
+on the next k3s restart or upgrade. Two alternatives were weighed and rejected:
+
+* **`coredns.yaml.skip` + our own templated copy** (the pattern `roles/kube_vip` already uses for a
+  file in `server/manifests`). Deterministic and never flaps, but it takes ownership of coredns away
+  from k3s permanently — k3s upgrades would stop updating it and the version would need refreshing
+  by hand forever. Too high a price for a replica count.
+* **A Flux-managed patch of the Deployment.** Rejected outright: Flux and k3s's deploy controller
+  would both own one object and fight continuously — the exact shape of the `default-deny`
+  NetworkPolicy drift loop this cluster already suffered (~2500 events/10min).
+
+An HPA avoids both: a separate object k3s does not own, driving the `/scale` subresource rather than
+the Deployment spec, so there is no shared-ownership fight. If k3s re-stages `replicas: 1`, the HPA
+sees it below `minReplicas` and scales back within one reconcile.
+
+It is a **floor-holder, not an autoscaler**: the CPU metric exists only because an `autoscaling/v2`
+HPA needs one to be valid. `scaleDown.stabilizationWindowSeconds: 600` because DNS is the worst
+thing in the cluster to flap; `scaleUp` is immediate, since that is the path that restores redundancy
+after a k3s restart.
+
+**Immediate action taken outside this PR:** `kubectl -n kube-system scale deploy coredns
+--replicas=2` was run at the operator's explicit request, so the cluster has two replicas **now**
+rather than after merge. That hand scale is what this PR makes durable.
+
+## What I verified
+
+* **The defect:** `kubectl -n kube-system get deploy coredns` → `replicas=1 available=1`.
+* **k3s ownership:** the `AddOn/coredns` object exists with source
+  `/data/k3s/server/manifests/coredns.yaml`; the Deployment has no `ownerReferences` but carries
+  `objectset.rio.cattle.io/hash` and `managedFields` managers `deploy@k3s-prod-1` / `k3s`. So it is
+  k3s-managed, not Flux-managed — independently corroborated by another agent, which confirmed
+  `platform/coredns/` contains **only** the `coredns-custom` ConfigMap and does not touch the
+  Deployment or its replica count.
+* **The hand scale works and holds:** coredns went to `2/2 Running` on two different nodes, and
+  in-cluster DNS kept answering throughout (`nslookup kubernetes.default.svc.cluster.local
+  10.43.0.10` → `10.43.0.1`). Still `spec.replicas=2 ready=2` after ~2 minutes, with the AddOn
+  checksum **unchanged** — so k3s's deploy controller does not revert on a drift timer; it
+  re-applies on manifest change and on restart.
+* **The HPA's preconditions hold:** coredns ships `requests: {cpu: 100m, memory: 70Mi}` (so a
+  Resource/Utilization metric is meaningful), and metrics-server is installed as a k3s addon and
+  verified serving — `kubectl top pod -l k8s-app=kube-dns` returns **5m and 4m** against that 100m
+  request, i.e. ~5% utilisation, confirming the 80% target will never be approached and the HPA will
+  sit at `minReplicas`.
+* **The kustomization edit is additive:** `git diff --stat` is `1 file changed, 4 insertions(+)`,
+  and `- coredns` was already registered in `platform/kustomization.yaml`, so no change was needed
+  there.
+* All three touched/added YAML files parse.
+
+## What I did NOT verify
+
+* **The HPA has never been applied.** I did not reconcile it, so I have **not** observed it create,
+  reach `ScalingActive=True`, resolve its metric against real coredns data, or hold `minReplicas`.
+  Applying is an operator action (CLAUDE.md §5). The failure mode to watch for is
+  `ScalingActive=False` with `FailedGetResourceMetric` — the HPA would then be present and inert,
+  which looks identical to working because the hand scale already left 2 replicas in place. **Check
+  `kubectl -n kube-system describe hpa coredns` after merge**, not just the replica count.
+* **The central claim that k3s reverts `replicas` on restart is REASONED, NOT OBSERVED.** It rests
+  on k3s re-staging bundled manifests at startup plus the measured ownership evidence above. I did
+  **not** restart k3s to watch the revert happen — doing so is a rolling control-plane restart, an
+  operator action. If k3s in fact preserves a modified replica count, this HPA is unnecessary
+  (though harmless).
+* **I did not confirm the HPA wins the race against k3s's deploy controller after a restart.** Both
+  write the scale; the expectation is the HPA re-asserts within a reconcile, leaving a brief window
+  at 1 replica. Neither the window's length nor the outcome has been measured.
+* **I nearly shipped a destructive change.** My first write of
+  `platform/coredns/kustomization.yaml` replaced the file wholesale, listing only `hpa.yaml` — which
+  would have pruned the existing `coredns-custom` ConfigMap and **broken in-cluster split-horizon
+  DNS (R-DNS-01/03)**. It was caught by a guard assertion before commit and restored from `HEAD`, and
+  the diff is now additive. Recorded because the near-miss is the useful part: `platform/coredns/`
+  already existed and I assumed it did not. **No conformance check would obviously have caught the
+  removal** — it is valid YAML and a legitimate-looking prune.
+* **Whether 2 is enough.** Three nodes, and coredns' anti-affinity only *prefers* spreading, so both
+  replicas could in principle land on one node and a single drain would still take DNS down. I did
+  not add a `topologySpreadConstraint` or a PodDisruptionBudget — both arguably belong here and
+  neither is in this change.
+* **No alert fires if coredns drops to 1 replica**, so a future silent regression (k3s upgrade
+  changing the manifest, the HPA going inert) would not be reported. That gap is not closed here.
+* **No conformance test asserts this**, so a future edit could remove the HPA with no gate stage
+  noticing.
+* **No runtime conformance.** `vars.CLUSTER_AVAILABLE` is unset, so CI proves the L0/L1 offline
+  subset only.
+* I did not re-measure branch protection or runner state (CLAUDE.md §2b).
@@ -0,0 +1,76 @@
+---
+date: 2026-10-18
+branch: fix/ha-check-catastrophic-regex
+title: "One regex made the merge gate take 28 minutes instead of 2"
+---
+
+## What changed
+
+The merge gate started taking **~28 minutes** instead of its usual **<2 minutes**, on every change
+touching `infra/**`. One regex was responsible for essentially all of it.
+
+`conformance/tests/l0-static/ha-control-plane-as-code/check.sh` contained:
+
+```python
+join_when = re.search(r"--server https://.*?\n(?:.*\n){0,10}?\s*when:\s*k3s_server_mode\s*==\s*'secondary'",
+                      K3S_TEXT, re.S)
+```
+
+With `re.S`, every `.` also matches newlines, so `.*?` and the nested `(?:.*\n){0,10}?` can each
+consume the entire document. That is **nested unbounded repetition** — ten levels of a quantifier
+that can each swallow everything — and a failed or late match backtracks exponentially.
+
+Replaced `.` with `[^\n]*` and dropped `re.S`, so the `{0,10}` is a genuine ten-line window with
+nothing to backtrack into. Same intent, same verdict, no DOTALL.
+
+**Why it surfaced now, and it was mine.** `K3S_TEXT` is every `*.yml` in `roles/k3s_server`
+concatenated. The regex was latent for as long as it existed; **PR #71 added ~100 lines to that role
+(the kubelet graceful-shutdown config), which grew the input past the point where exponential
+backtracking stopped being survivable.** Nothing about the check changed — my change grew its input.
+
+**Why only `infra/**` changes were slow.** `ci/touched-requirements.sh:268` maps `infra/*` to
+`R-ENV-01`, and the resulting L0 run is `--include-scope whole-repo --requirements R-ENV-01`, which
+pulls in this whole-repo check. Doc-only and `platform/**` changes never selected it, which is why
+#69 (1m55s) and #72 (1m53s) stayed fast while #71 (27m44s), the #73 merge (27m46s) and #75 all ran
+~28 minutes.
+
+## What I verified
+
+* **The hot spot, by measurement rather than reading.** `docker top` on the live CI job container for
+  run #299 showed `python3 -` with **19:54 of CPU time** under
+  `ha-control-plane-as-code/check.sh`, inside
+  `conformance/run.sh --layer l0 --include-scope whole-repo --requirements R-ENV-01`.
+* **Reproduced locally**: the check did not finish within a 100-second budget on an unmodified
+  checkout.
+* **Localised to the exact line** by extracting the inline Python and running it under
+  `faulthandler.dump_traceback_later(25)`, which named `re/__init__.py:177 in search` called from
+  the `join_when` line — not inferred from reading the patterns.
+* **The pattern is unique in the repo**: `grep -rlnE "\{0,[0-9]+\}\?" conformance/tests/l0-static/*/check.sh`
+  returns only this file, so there is no sibling with the same hazard.
+* **The fix is fast AND verdict-preserving**, tested against the real `K3S_TEXT` (22,179 chars, 403
+  lines): the new regex matches (`YES`) in **0.2 ms**. Sanity-checked that the thing it looks for
+  genuinely exists — one `--server https://` and three `k3s_server_mode == 'secondary'` occurrences.
+* **The whole check now runs in 0.199s, rc 0, 115 assertions**, with the same success message as
+  before.
+
+## What I did NOT verify
+
+* **I did not re-time the full gate in CI after the fix.** The expectation is that `infra/**` changes
+  return to the ~2-minute range, but that is arithmetic from the 19m54s figure, not a measured
+  post-fix run. The PR's own CI run is the first real datapoint — read it.
+* **I did not audit the other 23 L0 checks for different performance pathologies.** This one was
+  found because it was actively burning CPU in a live job; a check that is merely slow (not
+  exponential) would not have stood out, and `ci/gate.sh` has **no per-stage timing** at all
+  (`grep -nE "SECONDS|date \+|elapsed"` finds nothing), so there is no data on where the remaining
+  time goes.
+* **Nothing prevents this class of bug returning.** No check asserts gate stage runtime, and no lint
+  forbids nested quantifiers under `re.S`. A timing budget per stage, or a `re` lint, would close it;
+  neither is written here.
+* **I did not verify my claim about *why* only `infra/**` was affected beyond the path mapping and
+  the observed durations.** The correlation is strong (5 runs, two clear clusters) and the live
+  process list confirms the `--requirements R-ENV-01` scope, but I did not read
+  `conformance/run.sh`'s scope-selection logic end to end.
+* The regex rewrite assumes the `when:` clause is indented with spaces or tabs only (`[ \t]*`). A
+  file using some other whitespace before `when:` would now fail to match where the old DOTALL
+  version would have succeeded. Unlikely in YAML, and the current input matches, but it is a
+  narrowing.
@@ -0,0 +1,78 @@
+---
+date: 2026-10-18
+branch: fix/renovate-invalid-config
+title: "renovate.json was invalid, so the first manual run errored out"
+---
+
+## What changed
+
+The operator ran the Renovate workflow manually and it **failed**. The cause is not the workflow:
+**`renovate.json` was never a valid Renovate config.**
+
+It carried five pseudo-comment keys — `_comment`, `_kubernetes_comment`, `_unmanageable_comment`,
+`_ignorePaths_comment`, `_docker_comment` — because JSON has no comments. Renovate **rejects unknown
+top-level options**, so the entire config failed validation. Proven with the official validator
+rather than inferred:
+
+```
+$ podman run --rm -v "$PWD/renovate.json:/tmp/renovate.json:ro,Z" \
+    ghcr.io/renovatebot/renovate renovate-config-validator /tmp/renovate.json
+ERROR: Found errors in configuration
+  Invalid configuration option: _comment
+  Invalid configuration option: _docker_comment
+  Invalid configuration option: _ignorePaths_comment
+  Invalid configuration option: _kubernetes_comment
+  Invalid configuration option: _unmanageable_comment
+```
+
+This is the second independent reason Renovate had never worked, on top of PR #77's cron firing
+outside `renovate.json`'s own schedule window. Either alone was sufficient to produce "nothing ever
+happens"; #73 shipped both.
+
+**Converted `renovate.json` → `renovate.json5`.** JSON5 permits real `//` comments, and Renovate
+discovers `renovate.json5` natively — nothing in `.gitea/` or `ci/` pins the old filename (only
+prose inside comments), and no `RENOVATE_CONFIG_FILE` is set. Every word of the original rationale
+is preserved as comments positioned next to what it explains, which a flattened `description`
+string would have lost.
+
+A header on the new file records the failure, the validator command, and the instruction to run it
+before committing — this class of bug is invisible to the repo's own gate.
+
+## What I verified
+
+* **The exact failure**, from the official validator, quoted above. Not read off a log, not inferred
+  from the workflow.
+* **The fix validates**: the same validator against `renovate.json5` returns
+  `INFO: Config validated successfully against 1 file(s)`.
+* **Nothing was dropped in the conversion**, checked programmatically against `git show
+  HEAD:renovate.json`: 18 non-comment keys before, 18 after, **no missing keys, no extra keys, and
+  no key whose value changed**. `docker: {enabled: true}` confirmed still present — the validator
+  prints a normalisation diff that mentions it, which is its own migration suggestion, not a
+  removal.
+* **74 comment lines survive** in the new file, so the rationale is intact.
+* **`RENOVATE_TOKEN` exists** as a repository Actions secret (listed by name via the Gitea API), so
+  the workflow's fail-hard preflight is satisfied.
+* **A suspicion was DISPROVED:** `enabledManagers` containing bare `regex` was thought to need to be
+  `custom.regex`, which would have silently disabled every inline `# renovate:` marker. The
+  validator accepts `regex`, so that concern was unfounded and nothing here changes it.
+* Nothing functionally references `renovate.json` by name — `grep -rn "renovate\.json" .gitea/ ci/
+  conformance/` returns only comment prose.
+
+## What I did NOT verify
+
+* **Renovate has still never completed a run.** This removes one of two blockers; PR #77 removes the
+  other. Neither is merged, so **no successful Renovate run has been observed** and I cannot say the
+  bot works — only that these two specific defects are fixed.
+* **I did not re-run the workflow after the fix.** The honest test is a `workflow_dispatch` with
+  `dry_run: true` once both this and #77 are merged. Expect ~30 dependencies behind, rate-limited to
+  `prHourlyLimit: 2` / `prConcurrentLimit: 5`.
+* **Whether the managers actually extract anything.** A valid config that matches no files is still
+  a no-op. The dry-run log's per-manager dependency counts are the only thing that proves the
+  `managerFilePatterns` are right, and I have not seen them.
+* **Whether `renovate.json5` is honoured by the pinned Renovate version in the workflow.** JSON5
+  discovery is long-standing and the validator accepted the file, but the workflow's image tag was
+  not cross-checked against the version that added it.
+* **Nothing in the gate catches an invalid Renovate config.** This bug would have recurred silently.
+  A one-line L0 check shelling out to `renovate-config-validator` would close it; it is not written
+  here, and `conformance/**` is a sensitive path.
+* I did not re-measure branch protection or runner state (CLAUDE.md §2b).
@@ -107,3 +107,31 @@ k3s_base_domain: "home.keithjackson.dev"

 # Derived, so the realm path is stated once. Override k3s_base_domain, not this.
 k3s_oidc_issuer_url: "https://keycloak.{{ k3s_base_domain }}/realms/homelab"
+
+# --- Graceful node shutdown (kubelet) ----------------------------------------------------------
+# MEASURED 2026-10-17, during the UPS move: graceful node shutdown was NOT configured on any prod
+# node, so `shutdown -h` did NOT drain pods. systemd stops k3s, containerd goes with it, and every
+# pod is SIGKILLed where it stands -- including 9 CloudNativePG instances mid-checkpoint, the UniFi
+# VM, and 25 attached Longhorn volumes. The whole-cluster shutdown that day had to quiesce
+# everything BY HAND first (runbooks/cluster-maintenance-shutdown.md), and the one volume that did
+# not finish detaching came back `degraded` and had to rebuild.
+#
+# With these set, the kubelet takes a systemd inhibitor lock and, on shutdown, evicts ordinary pods
+# first and critical ones last, so a plain `shutdown -h`/reboot drains the node. That makes the
+# manual scale-down in the runbook a belt-and-braces step for a PLANNED whole-cluster shutdown
+# rather than the only thing standing between a reboot and a hard kill.
+#
+# 90s/20s, not larger: the budget is spent on every reboot and node upgrade, and the kubelet waits
+# the FULL ordinary period before it starts on critical pods. Postgres does a fast shutdown in
+# well under 90s here, and Longhorn needs only enough time to flush and detach.
+k3s_kubelet_shutdown_grace_period: "90s"
+k3s_kubelet_shutdown_grace_period_critical_pods: "20s"
+
+# *** THE HALF THAT IS EASY TO MISS, AND SILENTLY BREAKS THE OTHER HALF. ***
+# Graceful node shutdown works by the kubelet holding a logind INHIBITOR DELAY lock. systemd caps
+# how long any inhibitor may delay shutdown at `InhibitDelayMaxSec`, which DEFAULTS TO 5 SECONDS.
+# If that cap is below the grace period above, systemd proceeds anyway and the drain is truncated
+# to ~5s -- i.e. the feature appears configured, reports no error, and still hard-kills pods. So
+# this MUST be >= k3s_kubelet_shutdown_grace_period; the role asserts it rather than trusting it.
+# Set a little above the kubelet's total (90s + 20s) to leave headroom.
+k3s_logind_inhibit_delay_max_sec: 120
@@ -15,3 +15,12 @@
    port: "{{ k3s_api_port }}"
    timeout: 180
  listen: Restart k3s
+
+# logind re-reads InhibitDelayMaxSec only on restart. Restarting logind does NOT log users out or
+# disturb k3s -- it manages login sessions and inhibitor locks, not workloads. The kubelet picks up
+# the new cap when it next takes its lock, so no k3s restart is needed for THIS half.
+- name: Restart logind
+  ansible.builtin.systemd_service:
+    name: systemd-logind
+    state: restarted
+  listen: Restart logind
@@ -86,6 +86,16 @@
      # k3s_base_domain (defaults/main.yml), whose [parity] contract with the cluster's
      # BASE_DOMAIN is documented there. Dev's default renders the value it already runs, so
      # config.yaml is unchanged and the Restart handler does not fire.
+      # ── Graceful node shutdown ──────────────────────────────────────────────────────────────
+      # Without these the kubelet takes no systemd inhibitor lock, so `shutdown -h` stops
+      # containerd and SIGKILLs every pod where it stands -- MEASURED on all three prod nodes
+      # 2026-10-17 (defaults/main.yml has the detail). The companion logind drop-in below raises
+      # InhibitDelayMaxSec, WITHOUT WHICH systemd caps the drain at ~5s and these values are
+      # quietly ignored.
+      kubelet-arg:
+        - "shutdown-grace-period={{ k3s_kubelet_shutdown_grace_period }}"
+        - "shutdown-grace-period-critical-pods={{ k3s_kubelet_shutdown_grace_period_critical_pods }}"
+
      kube-apiserver-arg:
        - "oidc-issuer-url={{ k3s_oidc_issuer_url }}"
        - "oidc-client-id=kubernetes"
@@ -183,3 +193,46 @@
    host: "127.0.0.1"
    port: "{{ k3s_api_port }}"
    timeout: 180
+
+# ── Graceful node shutdown: the systemd half — tag `shutdown` ──────────────────────────────────
+# The kubelet's shutdown-grace-period is ENFORCED BY logind, not by the kubelet: the kubelet holds
+# an inhibitor DELAY lock, and systemd will wait at most `InhibitDelayMaxSec` for it (default 5s)
+# before proceeding regardless. A grace period above that cap is therefore silently truncated --
+# the feature looks configured, logs no error, and still hard-kills pods. Assert the relationship
+# instead of documenting it, because the failure is invisible.
+- name: Assert the logind inhibitor cap can actually cover the kubelet grace period
+  ansible.builtin.assert:
+    that:
+      - (k3s_logind_inhibit_delay_max_sec | int) >= (k3s_kubelet_shutdown_grace_period | regex_replace('[^0-9]', '') | int)
+    fail_msg: >-
+      k3s_logind_inhibit_delay_max_sec ({{ k3s_logind_inhibit_delay_max_sec }}s) is below
+      k3s_kubelet_shutdown_grace_period ({{ k3s_kubelet_shutdown_grace_period }}). systemd would
+      stop waiting for the kubelet's inhibitor lock before the drain finished, so pods would be
+      SIGKILLed anyway and graceful node shutdown would be configured but ineffective.
+    quiet: true
+  tags: [shutdown]
+
+- name: Ensure /etc/systemd/logind.conf.d exists
+  ansible.builtin.file:
+    path: /etc/systemd/logind.conf.d
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+  tags: [shutdown]
+
+# A drop-in, not an edit of logind.conf: the distro file stays pristine and `state: absent` here
+# would fully revert the change.
+- name: Raise the logind inhibitor delay cap so the kubelet can finish draining
+  ansible.builtin.copy:
+    dest: /etc/systemd/logind.conf.d/10-k3s-graceful-shutdown.conf
+    owner: root
+    group: root
+    mode: "0644"
+    content: |
+      # Managed by Ansible (roles/k3s_server). See defaults/main.yml.
+      # MUST stay >= kubelet shutdown-grace-period, or the drain is truncated to this value.
+      [Login]
+      InhibitDelayMaxSec={{ k3s_logind_inhibit_delay_max_sec }}
+  notify: Restart logind
+  tags: [shutdown]
@@ -20,10 +20,19 @@ restarted, and reboots are delegated to **kured** (`platform/kured`).

 Deploying either alone produces a mechanism that looks healthy and does nothing:

- **kured alone** watches a file that nothing creates. Measured 2026-10-17:
-  `update-notifier-common` — the package that owns the hook which writes
-  `/var/run/reboot-required` — was **not installed on any node**. kured would sit at 1/1 Running
-  reporting `kured_reboot_required=0` forever.
+- **kured alone** watches a file that **nothing on Debian ever creates**. Measured 2026-10-18,
+  after a first attempt to install Ubuntu's `update-notifier-common` failed on all three nodes
+  with *"No package matching 'update-notifier-common' is available"*:
+  - `apt-cache policy update-notifier-common` → `Candidate: (none)` — the package does not exist
+    in Debian; it is Ubuntu-only.
+  - `/usr/share/update-notifier/notify-reboot-required` → absent.
+  - **No `linux-image-*` postinst references `notify-reboot-required`** — calling it is an Ubuntu
+    patch, so even dropping a script at that path would never be invoked.
+  - No hook under `/etc/apt/apt.conf.d` or `/etc/kernel/` mentions `reboot-required`.
+
+  So **this role ships the writer itself** (`/usr/local/sbin/k3s-notify-reboot-required` plus a
+  `DPkg::Post-Invoke` hook) rather than installing a package. Without it kured would sit at 1/1
+  Running reporting `kured_reboot_required=0` forever.
 - **this role alone** installs patches that a long-running process never picks up, and when a
  reboot *is* needed there is nothing safe to take it. `Automatic-Reboot "true"` is not the
  answer: three control-plane nodes with etcd quorum 2/3, each rebooting at its own time, is how
@@ -36,7 +45,7 @@ Measured on all three prod nodes, 2026-10-17:
 | | |
 |---|---|
 | `unattended-upgrades` | **not installed** |
-| `update-notifier-common` | **not installed** |
+| `update-notifier-common` | **not installable** — Ubuntu-only, `Candidate: (none)` on trixie |
 | `needrestart` | **not installed** |
 | `apt-mark showhold` | **empty** — no package held on any node |
 | `/etc/apt/preferences.d/` | **empty** — no apt pin declares the backports-kernel intent |
@@ -157,7 +166,9 @@ first two):
 ```bash
 ssh [email protected] 'apt-config dump | grep -iE "unattended-upgrade::(automatic-reboot|package-blacklist|origins)"'
 ssh [email protected] 'systemctl list-timers apt-daily-upgrade.timer --no-pager'
-ssh [email protected] 'ls -la /var/run/reboot-required 2>&1; dpkg -l update-notifier-common needrestart unattended-upgrades | tail -4'
+ssh [email protected] 'ls -la /var/run/reboot-required* 2>&1 | head -2
+  ls -l /usr/local/sbin/k3s-notify-reboot-required /etc/apt/apt.conf.d/99-k3s-reboot-required 2>&1
+  dpkg -l needrestart unattended-upgrades | tail -3'
 ```

 Expect: `Automatic-Reboot "false"`, a blacklist containing `^linux-`, an `Origins-Pattern`
@@ -92,13 +92,11 @@ unattended_upgrades_enabled: false
 unattended_upgrades_packages:
  # The upgrader itself.
  - unattended-upgrades
-  # THE SENTINEL WRITER, AND THE WHOLE REASON kured CAN WORK. On Debian, /var/run/reboot-required is
-  # not created by the kernel, by apt, or by unattended-upgrades — it is created by a hook shipped in
-  # update-notifier-common. Measured ABSENT on all three nodes. Without this package the file is
-  # never written, kured correctly never reboots, every dashboard stays green, and the reboot half of
-  # this PR is an elaborate no-op. The role asserts the hook exists after install rather than
-  # assuming the package shipped one (see tasks/main.yml).
-  - update-notifier-common
+  # NOTE: `update-notifier-common` was listed here and REMOVED (2026-10-18). It is an UBUNTU
+  # package and does not exist in Debian at all -- `apt-cache policy update-notifier-common` on
+  # trixie returns `Candidate: (none)`, so the play failed outright with "No package matching
+  # 'update-notifier-common' is available" on all three nodes. The sentinel writer is now provided
+  # by this role itself; see unattended_upgrades_sentinel_* below and tasks/main.yml.
  # Restarts services still mapped to a deleted library after a security upgrade. Without it a
  # security-only policy patches bytes on disk that no running process reads — see DECISION 3.
  - needrestart
@@ -170,3 +168,32 @@ unattended_upgrades_needrestart_blacklist:
 unattended_upgrades_download_time: "03:30"
 unattended_upgrades_upgrade_time: "04:00"
 unattended_upgrades_randomised_delay: 60m
+
+
+# ── THE REBOOT SENTINEL, PROVIDED BY THIS ROLE ──────────────────────────────────────────────────
+# /var/run/reboot-required is the ONLY thing kured watches, and on Debian trixie **nothing creates
+# it**. Measured on all three nodes 2026-10-18:
+#   * `update-notifier-common` (which owns that hook on Ubuntu) has `Candidate: (none)` — the
+#     package does not exist in Debian. Installing it is what broke the first run of this play.
+#   * `/usr/share/update-notifier/notify-reboot-required` is absent.
+#   * NO `linux-image-*` postinst references `notify-reboot-required` — calling it is an Ubuntu
+#     patch, not Debian behaviour, so merely dropping a script at that path would never be invoked.
+#   * No hook under /etc/apt/apt.conf.d or /etc/kernel/ mentions reboot-required.
+# So the writer has to be ours. Without it kured is a permanent, INVISIBLE no-op: it stays 1/1
+# Running and reports kured_reboot_required=0 forever, which is the "failure mode is a green tick"
+# shape this repo keeps getting burned by.
+#
+# MECHANISM: a dpkg Post-Invoke hook runs a script that compares the RUNNING kernel against the
+# newest INSTALLED one and touches the sentinel when they differ. Deliberately kernel-only, which
+# matches the design: unattended-upgrades is security-only with `^linux-` blacklisted, so it will
+# essentially never set this — the sentinel appears when the OPERATOR deliberately runs the
+# node_baseline kernel play, and kured then automates only the mechanical reboot.
+#
+# It uses `linux-version` (from `linux-base`, a dependency of every linux-image package, so
+# guaranteed present — measured `linux-base 4.12.1` installed) rather than parsing `dpkg -l`
+# output, because kernel version ordering is not string ordering.
+#
+# /run is a tmpfs (measured), so the sentinel self-clears on boot: after a reboot the running
+# kernel IS the newest and the script writes nothing. No cleanup task is needed, and none exists.
+unattended_upgrades_sentinel_script: /usr/local/sbin/k3s-notify-reboot-required
+unattended_upgrades_sentinel_hook: /etc/apt/apt.conf.d/99-k3s-reboot-required
@@ -35,9 +35,9 @@
      tags: [packages, config, verify]

    # ── PACKAGES ────────────────────────────────────────────────────────────────────────────────
-    - name: Install unattended-upgrades, the reboot-sentinel writer and needrestart
-      # update-notifier-common is NOT optional padding: it owns the hook that creates
-      # /var/run/reboot-required, which is the only thing kured watches. See defaults/main.yml.
+    - name: Install unattended-upgrades and needrestart
+      # The reboot-sentinel writer is NOT a package here. On Debian nothing ships one -- see
+      # defaults/main.yml -- so this role installs its own script and dpkg hook, two tasks below.
      ansible.builtin.apt:
        name: "{{ unattended_upgrades_packages }}"
        state: present
@@ -45,6 +45,60 @@
        cache_valid_time: 3600
      tags: [packages]

+    # ── THE REBOOT SENTINEL WRITER (ours, because Debian ships none) ────────────────────────────
+    # Full rationale and the four measurements behind it: defaults/main.yml. Short version: kured
+    # watches /var/run/reboot-required and nothing on Debian creates it, so without these two files
+    # the entire reboot half is an invisible no-op.
+    - name: Install the reboot-sentinel writer
+      ansible.builtin.copy:
+        dest: "{{ unattended_upgrades_sentinel_script }}"
+        owner: root
+        group: root
+        mode: "0755"
+        content: |
+          #!/bin/sh
+          # MANAGED BY ANSIBLE -- infra/ansible/roles/unattended_upgrades. Local edits are reverted.
+          #
+          # Touch /var/run/reboot-required when the RUNNING kernel is not the newest INSTALLED one.
+          # kured watches that path; see the role's defaults/main.yml for why this is ours to ship.
+          #
+          # `linux-version` comes from linux-base (a dependency of every linux-image package), and
+          # is used rather than sorting `dpkg -l` output because kernel version ordering is not
+          # string ordering. If it is somehow missing, exit 0 and write nothing: a dpkg hook must
+          # never fail an apt transaction, and a missing sentinel is caught by the verify assert.
+          set -eu
+          command -v linux-version >/dev/null 2>&1 || exit 0
+
+          running="$(uname -r)"
+          newest="$(linux-version list 2>/dev/null | linux-version sort --reverse 2>/dev/null | head -n1)"
+
+          # No newest (nothing installed we can read) -> nothing to say.
+          [ -n "$newest" ] || exit 0
+
+          if [ "$running" != "$newest" ]; then
+            touch /var/run/reboot-required 2>/dev/null || exit 0
+            # kured only needs the file, but the .pkgs companion is what an operator reads to find
+            # out WHY a node is waiting, so write a reason rather than an empty marker.
+            printf 'linux-image-%s\n' "$newest" > /var/run/reboot-required.pkgs 2>/dev/null || true
+          fi
+          exit 0
+      tags: [packages, config]
+
+    - name: Install the dpkg hook that runs the sentinel writer
+      # Post-Invoke, so it runs after dpkg has finished and a newly installed kernel is already
+      # visible to `linux-version list`. `|| true` so a failure here can never abort an apt
+      # transaction -- an unwritten sentinel is a missed reboot, but a broken apt is a broken node.
+      ansible.builtin.copy:
+        dest: "{{ unattended_upgrades_sentinel_hook }}"
+        owner: root
+        group: root
+        mode: "0644"
+        content: |
+          // MANAGED BY ANSIBLE -- infra/ansible/roles/unattended_upgrades. Local edits reverted.
+          // Writes /var/run/reboot-required when the running kernel is not the newest installed.
+          DPkg::Post-Invoke { "{{ unattended_upgrades_sentinel_script }} || true"; };
+      tags: [packages, config]
+
    # ── CONFIG ──────────────────────────────────────────────────────────────────────────────────
    # Written as a whole file rather than patched in place, for the reason node_baseline gives for
    # its own apt source: an idempotent full-file write with a managed-by header is reviewable and
@@ -246,21 +300,24 @@
          Effective apt config confirmed: kernel blacklisted, automatic reboot disabled.
      tags: [verify]

-    - name: Find the hooks that can create /var/run/reboot-required
-      # THE SENTINEL IS THE SINGLE POINT OF FAILURE FOR THE ENTIRE REBOOT HALF OF THIS DESIGN, and
-      # it is the one part that cannot be asserted from the repo — it depends on what
-      # update-notifier-common actually ships on this Debian release. Rather than hard-code a path
-      # that may not exist, discover the candidates and assert that at least one is present.
-      ansible.builtin.find:
-        paths:
-          - /etc/kernel/postinst.d
-          - /etc/apt/apt.conf.d
-        patterns:
-          - "*update-notifier*"
-          - "*unattended-upgrades*"
-          - "99update-notifier"
-        file_type: any
-      register: unattended_upgrades_sentinel_hooks
+    # THE SENTINEL IS THE SINGLE POINT OF FAILURE FOR THE ENTIRE REBOOT HALF OF THIS DESIGN.
+    # This was originally a `find` over /etc/kernel/postinst.d and /etc/apt/apt.conf.d, on the
+    # theory that the writer came from a package and the role could only discover whatever that
+    # package happened to ship. That theory was wrong: no such package exists on Debian (see
+    # defaults/main.yml), so the writer is now OURS and lives at two known paths. Checking two
+    # exact paths is strictly stronger than a glob -- a glob would have matched Debian's own
+    # unattended-upgrades apt conffile and passed while no sentinel writer existed at all.
+    - name: Stat the sentinel writer script
+      ansible.builtin.stat:
+        path: "{{ unattended_upgrades_sentinel_script }}"
+      register: unattended_upgrades_sentinel_script_stat
+      changed_when: false
+      tags: [verify]
+
+    - name: Stat the sentinel dpkg hook
+      ansible.builtin.stat:
+        path: "{{ unattended_upgrades_sentinel_hook }}"
+      register: unattended_upgrades_sentinel_hook_stat
      changed_when: false
      tags: [verify]

@@ -272,18 +329,21 @@
      # before, so it is an assert and not a debug message.
      ansible.builtin.assert:
        that:
-          - unattended_upgrades_sentinel_hooks.matched | int > 0
+          - unattended_upgrades_sentinel_script_stat.stat.exists
+          - unattended_upgrades_sentinel_script_stat.stat.executable | default(false)
+          - unattended_upgrades_sentinel_hook_stat.stat.exists
        fail_msg: >-
-          NOTHING ON {{ inventory_hostname }} CAN CREATE /var/run/reboot-required. No
-          update-notifier / unattended-upgrades hook was found under /etc/kernel/postinst.d or
-          /etc/apt/apt.conf.d. kured watches that path and reboots only when it exists, so with no
-          writer the reboot automation is permanently and INVISIBLY idle -- kured stays 1/1 Running
-          and reports kured_reboot_required=0 on every node forever. Confirm
-          update-notifier-common is installed (`dpkg -l update-notifier-common`) and inspect
-          `dpkg -L update-notifier-common | grep -E 'postinst.d|apt.conf.d'`.
+          NOTHING ON {{ inventory_hostname }} CAN CREATE /var/run/reboot-required.
+          {{ unattended_upgrades_sentinel_script }} (executable) and
+          {{ unattended_upgrades_sentinel_hook }} must both exist -- this role ships both, because
+          Debian provides no sentinel writer of its own (update-notifier-common is an UBUNTU
+          package and is not installable here). kured watches that path and reboots only when it
+          exists, so with no writer the reboot automation is permanently and INVISIBLY idle --
+          kured stays 1/1 Running and reports kured_reboot_required=0 on every node forever.
+          Re-run this role without `--tags verify` to install them.
        success_msg: >-
-          Reboot sentinel writer present ({{ unattended_upgrades_sentinel_hooks.matched }} hook(s)
-          found) -- a kernel or flagged package upgrade will signal kured.
+          Reboot sentinel writer present ({{ unattended_upgrades_sentinel_script }} + dpkg hook)
+          -- a kernel change will signal kured on the next apt transaction.
      tags: [verify]

    - name: Report the pending-reboot state of this node
@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# =================================================================================================
+# quiesce.sh — bring the prod cluster to a safe standstill before powering nodes off, and bring it
+#              back afterwards. Companion to runbooks/cluster-maintenance-shutdown.md.
+# =================================================================================================
+# WHY THIS EXISTS. On 2026-10-17 all three nodes had to be powered off to move them onto a UPS, and
+# there was NO procedure for it: `infra/cluster.sh stop` is `virsh`-based and only ever applied to
+# the decommissioned dev cluster. The whole sequence was improvised live. This script is that
+# sequence, so the next person does not improvise it.
+#
+# WHY IT IS NOT JUST `shutdown -h`. Graceful node shutdown was unconfigured on every prod node that
+# day, so systemd stopped containerd and SIGKILLed every pod where it stood. roles/k3s_server now
+# sets shutdown-grace-period (+ the logind InhibitDelayMaxSec cap that actually enforces it), which
+# makes a bare reboot safe. This script is still the right tool for a PLANNED whole-cluster
+# shutdown, for three reasons the kubelet's drain does not cover:
+#   1. The UniFi VM needs an ACPI guest shutdown, not an eviction.
+#   2. CloudNativePG wants hibernation, not pod deletion -- and hibernation is IMPERATIVE state
+#      that Flux will not set or clear for you.
+#   3. Draining three nodes one at a time makes pods RESCHEDULE onto the survivors, churning
+#      Longhorn replicas for no reason when the whole cluster is going down anyway. Scaling in
+#      place avoids all of it.
+#
+# SAFE TO RE-RUN. Every step is idempotent and `resume` is the exact inverse of `quiesce`.
+#
+# WHAT IT DELIBERATELY DOES NOT DO: power anything off. Node poweroff is an operator action
+# (CLAUDE.md §5) and needs the become password; the runbook gives the ansible one-liner. It also
+# does not touch TrueNAS (not in the inventory, SSH refused -- web UI only) or the router.
+set -euo pipefail
+
+CONTEXT="${CONTEXT:-k3s-prod}"
+KUBECTL=(kubectl --context "$CONTEXT" --request-timeout=30s)
+TIMEOUT="${TIMEOUT:-600}"
+
+# The three CloudNativePG clusters, as namespace/name. Hibernation is per-Cluster.
+CNPG=(keycloak/keycloak-db nextcloud-db/nextcloud-db semaphore-db/semaphore-db)
+
+log()  { printf '\033[34m[quiesce]\033[0m %s\n' "$*"; }
+ok()   { printf '\033[32m[ ok ]\033[0m %s\n' "$*"; }
+warn() { printf '\033[33m[warn]\033[0m %s\n' "$*"; }
+die()  { printf '\033[31m[fail]\033[0m %s\n' "$*" >&2; exit 1; }
+
+need() { command -v "$1" >/dev/null || die "$1 not on PATH — run this inside ./infra/devcontainer/dev.sh"; }
+
+# ---------------------------------------------------------------- discovery
+# Every Deployment/StatefulSet whose pods mount a PVC — Longhorn OR the TrueNAS NFS bulk tier.
+# Computed from the LIVE cluster rather than hardcoded, so a newly onboarded service is covered
+# without anyone remembering to add it here. PROTECTED namespaces are excluded because scaling
+# them down would remove the very machinery that performs the detach (longhorn-system), keep the
+# API reachable (kube-system), or finish the hibernation and the VM shutdown (cnpg-system,
+# kubevirt).
+pvc_workloads() {
+  "${KUBECTL[@]}" get pods -A -o json | python3 -c '
+import json,sys
+PROTECT={"longhorn-system","kube-system","cilium-secrets","cnpg-system","kubevirt","flux-system","cdi"}
+out={}
+for p in json.load(sys.stdin)["items"]:
+    ns=p["metadata"]["namespace"]
+    if ns in PROTECT: continue
+    if not any(v.get("persistentVolumeClaim") for v in (p["spec"].get("volumes") or [])): continue
+    ow=(p["metadata"].get("ownerReferences") or [])
+    if not ow: continue
+    k,n=ow[0]["kind"],ow[0]["name"]
+    if k=="ReplicaSet": k,n="deployment",n.rsplit("-",1)[0]
+    elif k=="StatefulSet": k="statefulset"
+    else: continue          # Jobs, and CNPG Clusters, are handled separately
+    out[(ns,k,n)]=1
+for ns,k,n in sorted(out): print(ns,k,n)
+'
+}
+
+# ---------------------------------------------------------------- the PVC-deletion guard
+# *** DO NOT REMOVE THIS CHECK. IT EXISTS BECAUSE SCALING A StatefulSet DESTROYED DATA. ***
+# A StatefulSet may carry `persistentVolumeClaimRetentionPolicy.whenScaled: Delete`, and then
+# scaling it to 0 DELETES ITS PVCs -- and with them the Longhorn volumes. MEASURED 2026-10-17: the
+# quiesce for the UPS move scaled `monitoring/loki` (whenScaled: Delete) to 0 and its
+# `storage-loki-0` PVC and volume were deleted outright. Loki stores with `type: filesystem`, so
+# that PVC was the only copy; 72h retention bounded the loss to a rolling window, but nothing about
+# the mechanism is bounded -- the same action on a Delete-policy StatefulSet holding real state
+# would be unrecoverable. The volume count going 25 -> 24 was the only visible symptom, and it was
+# first misread as a miscount.
+#
+# So: such a StatefulSet is NEVER scaled. It is left RUNNING and its volume hard-detaches at
+# poweroff, which costs a replica rebuild on restart (degraded -> healthy, automatic). A rebuild is
+# an enormously better outcome than a deletion, and that is the whole trade being made here.
+sts_deletes_pvc_on_scale() { # ns name -> 0 if scaling it would delete its PVCs
+  local policy
+  policy=$("${KUBECTL[@]}" -n "$1" get statefulset "$2" \
+            -o jsonpath='{.spec.persistentVolumeClaimRetentionPolicy.whenScaled}' 2>/dev/null || true)
+  [ "$policy" = "Delete" ]
+}
+
+wait_for() { # wait_for <description> <shell-condition>
+  local desc="$1" cond="$2" waited=0
+  log "waiting: $desc (up to ${TIMEOUT}s)"
+  until eval "$cond"; do
+    (( waited += 10 )); (( waited >= TIMEOUT )) && { warn "TIMED OUT waiting: $desc"; return 1; }
+    sleep 10
+  done
+  ok "$desc"
+}
+
+# ---------------------------------------------------------------- quiesce
+do_quiesce() {
+  need kubectl; need python3
+
+  # Refuse to start if Longhorn is already unhealthy. Powering off on top of a degraded volume is
+  # how one replica becomes zero; better to stop here and let it rebuild first.
+  local unhealthy
+  unhealthy=$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io \
+    -o jsonpath='{range .items[*]}{.status.robustness}{"\n"}{end}' | grep -cvE '^(healthy|unknown)$' || true)
+  [ "$unhealthy" = "0" ] || die "$unhealthy Longhorn volume(s) are not healthy — fix or wait for rebuild BEFORE powering off"
+  ok "Longhorn: all volumes healthy"
+
+  # 1. Flux first, or it reverts every scale-down below within its reconcile interval.
+  log "suspending Flux Kustomizations"
+  local k
+  for k in $("${KUBECTL[@]}" -n flux-system get kustomizations -o name); do
+    "${KUBECTL[@]}" -n flux-system patch "${k}" --type=merge -p '{"spec":{"suspend":true}}' >/dev/null
+  done
+  ok "all Kustomizations suspended"
+
+  # 2. The VM needs an ACPI shutdown of the GUEST. KubeVirt does that on running:false; a plain
+  #    pod eviction would be a power cut to the VM.
+  if "${KUBECTL[@]}" -n unifi get vm unifi >/dev/null 2>&1; then
+    log "ACPI-stopping the UniFi VM"
+    "${KUBECTL[@]}" -n unifi patch vm unifi --type=merge -p '{"spec":{"running":false}}' >/dev/null
+  fi
+
+  # 3. Postgres: hibernation is a clean smart shutdown that KEEPS the PVCs. CNPG does one instance
+  #    at a time, primary last-ish, so this is not instant.
+  log "hibernating CloudNativePG clusters"
+  local c ns name
+  for c in "${CNPG[@]}"; do
+    ns="${c%%/*}"; name="${c##*/}"
+    "${KUBECTL[@]}" -n "$ns" annotate cluster.postgresql.cnpg.io "$name" \
+      cnpg.io/hibernation=on --overwrite >/dev/null 2>&1 || warn "could not hibernate $c"
+  done
+
+  # 4. Everything holding a PVC, scaled in place. NFS consumers first so nothing holds a hard
+  #    TrueNAS mount; PiHole last because it is the LAN resolver.
+  log "scaling down PVC-holding workloads"
+  local line ns2 kind nm deferred=() skipped_delete_policy=()
+  while read -r ns2 kind nm; do
+    [ -z "${ns2:-}" ] && continue
+    if [ "$kind" = "statefulset" ] && sts_deletes_pvc_on_scale "$ns2" "$nm"; then
+      warn "SKIPPING $ns2/$nm — whenScaled: Delete would DELETE its PVC (see the guard above)."
+      warn "  Left running; its volume hard-detaches at poweroff and rebuilds on restart."
+      skipped_delete_policy+=("$ns2/$nm")
+      continue
+    fi
+    if [ "$ns2" = "pihole" ]; then deferred+=("$ns2 $kind $nm"); continue; fi
+    "${KUBECTL[@]}" -n "$ns2" scale "$kind" "$nm" --replicas=0 >/dev/null 2>&1 \
+      && printf '    scaled 0  %s/%s %s\n' "$ns2" "$kind" "$nm" \
+      || warn "could not scale $ns2/$kind/$nm"
+  done < <(pvc_workloads)
+  for line in "${deferred[@]:-}"; do
+    [ -z "${line:-}" ] && continue
+    # shellcheck disable=SC2086
+    set -- $line
+    "${KUBECTL[@]}" -n "$1" scale "$2" "$3" --replicas=0 >/dev/null 2>&1 \
+      && printf '    scaled 0  %s/%s %s  (LAN DNS — expect name resolution to stop)\n' "$1" "$2" "$3"
+  done
+
+  # 5. The only assertion that matters. An attached volume at poweroff comes back degraded and
+  #    rebuilds; this is what we are buying with all of the above.
+  wait_for "UniFi VMI gone" \
+    '[ "$('"${KUBECTL[*]}"' -n unifi get vmi --no-headers 2>/dev/null | wc -l)" = "0" ]' || true
+  wait_for "all Postgres instances stopped" \
+    '[ "$('"${KUBECTL[*]}"' get pods -A --no-headers 2>/dev/null | grep -cE "(keycloak|nextcloud|semaphore)-db-[0-9]")" = "0" ]' || true
+  wait_for "all Longhorn volumes detached" \
+    '[ "$('"${KUBECTL[*]}"' -n longhorn-system get volumes.longhorn.io -o jsonpath="{range .items[*]}{.status.state}{\"\n\"}{end}" 2>/dev/null | grep -c attached)" = "0" ]' || \
+      warn "some volumes are STILL ATTACHED — they will come back degraded and rebuild; acceptable, but note which"
+
+  if [ "${#skipped_delete_policy[@]}" -gt 0 ]; then
+    echo
+    warn "NOT scaled down (whenScaled: Delete — scaling them would delete their PVCs):"
+    printf '      %s\n' "${skipped_delete_policy[@]}"
+    warn "Expect these volumes to come back 'degraded' and rebuild. That is correct and automatic."
+  fi
+  echo
+  ok "QUIESCED. Safe to power off."
+  cat <<'NEXT'
+
+  Next, from inside the devcontainer (it holds the become password):
+    cd /work/infra/ansible && ansible -i inventory/hosts.ini k3s_prod -b \
+      -m shell -a 'shutdown -h +1 "maintenance"'
+
+  THEN, in this order and not before:
+    1. TrueNAS (192.168.2.30) — web UI only; not in the ansible inventory and SSH is refused.
+    2. Router / switch last.
+NEXT
+}
+
+# ---------------------------------------------------------------- resume
+do_resume() {
+  need kubectl
+
+  # THE STEP THAT IS ALWAYS FORGOTTEN. Hibernation is imperative state: Flux neither sets nor
+  # clears it, so resuming Flux alone leaves all three databases down and every app that needs
+  # one looking broken for reasons that point nowhere near Postgres.
+  log "un-hibernating CloudNativePG clusters"
+  local c ns name
+  for c in "${CNPG[@]}"; do
+    ns="${c%%/*}"; name="${c##*/}"
+    "${KUBECTL[@]}" -n "$ns" annotate cluster.postgresql.cnpg.io "$name" \
+      cnpg.io/hibernation=off --overwrite >/dev/null 2>&1 || warn "could not un-hibernate $c"
+  done
+
+  # Flux restores every replica count AND the VM's running:true from git, so nothing here needs to
+  # undo the scale-downs by hand.
+  log "resuming Flux Kustomizations"
+  local k
+  for k in $("${KUBECTL[@]}" -n flux-system get kustomizations -o name); do
+    "${KUBECTL[@]}" -n flux-system patch "${k}" --type=merge -p '{"spec":{"suspend":false}}' >/dev/null
+  done
+  ok "all Kustomizations resumed"
+
+  wait_for "Flux fully reconciled" \
+    '[ "$('"${KUBECTL[*]}"' -n flux-system get kustomizations --no-headers 2>/dev/null | grep -vc True)" = "0" ]' || \
+      warn "some Kustomizations are not Ready — the graph serialises behind platform-config, so give it a few minutes before worrying"
+
+  echo
+  ok "RESUMED."
+  cat <<'NEXT'
+
+  Known cold-start race, not a fault in this script: oauth2-proxy performs OIDC discovery at
+  startup and exits 1 on the 503 it gets while Keycloak is still coming up, then sits in
+  exponential CrashLoopBackOff. If a replica is stuck, delete the pod once:
+    kubectl --context k3s-prod -n oauth2-proxy delete pod <name>
+NEXT
+}
+
+do_status() {
+  need kubectl
+  printf 'nodes:      %s Ready\n' "$("${KUBECTL[@]}" get nodes --no-headers | grep -c ' Ready')"
+  printf 'flux:       %s/%s Ready\n' \
+    "$("${KUBECTL[@]}" -n flux-system get kustomizations --no-headers | grep -c True)" \
+    "$("${KUBECTL[@]}" -n flux-system get kustomizations --no-headers | wc -l)"
+  printf 'longhorn:   %s attached, %s detached, %s not healthy\n' \
+    "$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io -o jsonpath='{range .items[*]}{.status.state}{"\n"}{end}' | grep -c attached)" \
+    "$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io -o jsonpath='{range .items[*]}{.status.state}{"\n"}{end}' | grep -c detached)" \
+    "$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io -o jsonpath='{range .items[*]}{.status.robustness}{"\n"}{end}' | grep -cvE '^(healthy|unknown)$' || true)"
+  printf 'postgres:   %s instance pod(s)\n' \
+    "$("${KUBECTL[@]}" get pods -A --no-headers | grep -cE '(keycloak|nextcloud|semaphore)-db-[0-9]' || true)"
+  printf 'unifi VM:   %s VMI\n' "$("${KUBECTL[@]}" -n unifi get vmi --no-headers 2>/dev/null | wc -l)"
+}
+
+case "${1:-}" in
+  quiesce) do_quiesce ;;
+  resume)  do_resume ;;
+  status)  do_status ;;
+  *) cat >&2 <<USAGE
+usage: $0 {quiesce|resume|status}
+
+  quiesce  suspend Flux, ACPI-stop the UniFi VM, hibernate Postgres, scale down every
+           PVC-holding workload, and wait for all Longhorn volumes to detach.
+           Does NOT power anything off — see runbooks/cluster-maintenance-shutdown.md.
+  resume   the exact inverse: un-hibernate Postgres, resume Flux, wait for reconcile.
+  status   one-screen readout of nodes / Flux / Longhorn / Postgres / VM.
+
+Run it inside the pinned toolbox, which supplies kubectl and the context:
+  ./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh status'
+USAGE
+     exit 2 ;;
+esac
@@ -0,0 +1,112 @@
+---
+# =================================================================================================
+# coredns HA floor — hold in-cluster DNS at >= 2 replicas, which k3s does not.
+# =================================================================================================
+# MEASURED on prod 2026-10-18: `kube-system/coredns` ran with **replicas: 1**. In-cluster DNS is a
+# single pod on a single node, so **draining or rebooting that one node is a cluster-wide
+# in-cluster DNS outage** for as long as the pod takes to reschedule and become ready — every pod
+# that looks up a Service, every CNPG replica finding its primary, every operator talking to the
+# API by name. It is the single cheapest availability defect in the cluster, and it was invisible
+# because `1/1 Ready` looks perfectly healthy.
+#
+# This matters more now than it did: the reboot automation (kured + unattended-upgrades) drains and
+# reboots one node at a time on a schedule, which turns a latent single point of failure into a
+# recurring one, unattended, in the middle of the night.
+#
+# -------------------------------------------------------------------------------------------------
+# WHY AN HPA, AND NOT JUST `replicas: 2` — this is the whole decision
+# -------------------------------------------------------------------------------------------------
+# **k3s owns the coredns Deployment and we cannot durably edit it.** It is applied by k3s's own
+# deploy controller from a bundled manifest, not by Flux:
+#
+#   $ kubectl -n kube-system get addon coredns
+#   NAME      SOURCE                                        CHECKSUM
+#   coredns   /data/k3s/server/manifests/coredns.yaml        8cd91595...
+#   $ kubectl -n kube-system get deploy coredns -o jsonpath='{.metadata.managedFields[*].manager}'
+#   deploy@k3s-prod-1 k3s
+#
+# and the Deployment carries an `objectset.rio.cattle.io/hash` label — a wrangler objectset. k3s
+# RE-STAGES its bundled manifests on startup, so a `replicas: 2` written into that file (or a
+# `kubectl scale`) is reverted the next time k3s restarts or is upgraded. MEASURED the same day: a
+# hand `kubectl scale` to 2 was NOT actively reverted (it held, and the AddOn checksum did not
+# change) — the deploy controller re-applies on manifest change and on restart, not on a drift
+# timer. So the hand fix survives until exactly the event we are protecting against: a reboot.
+#
+# The two durable alternatives were weighed and rejected:
+#   * **`coredns.yaml.skip` + our own templated copy** (the pattern roles/kube_vip already uses for
+#     a manifest in server/manifests). Fully deterministic and never flaps — but it takes OWNERSHIP
+#     of coredns away from k3s permanently, so k3s upgrades would stop updating it and the version
+#     would have to be refreshed by hand forever. Too high a price for a replica count.
+#   * **A Flux-managed patch of the Deployment itself.** Rejected outright: Flux and k3s's deploy
+#     controller would both own one object and fight continuously. That is the shape of the
+#     `default-deny` NetworkPolicy drift loop this cluster already suffered (Kyverno generate + Flux
+#     both owning one resource, ~2500 events per 10 minutes).
+#
+# An HPA avoids both. It is a SEPARATE object that k3s does not own and will never reconcile away,
+# and it drives the Deployment's `/scale` subresource rather than its spec — so there is no
+# shared-ownership fight. If k3s re-stages `replicas: 1`, the HPA observes it under `minReplicas`
+# and scales back to 2 within one reconcile (~15s by default).
+#
+# THE COST, STATED PLAINLY: there is a brief window — seconds, after a k3s restart — where coredns
+# is back at 1 replica until the HPA notices. That is strictly better than the status quo, where it
+# is at 1 replica permanently, but it is not zero. Accepting that window is the trade being made
+# here; the `.skip` option above is what to reach for if it ever proves unacceptable.
+#
+# -------------------------------------------------------------------------------------------------
+# THIS IS A FLOOR-HOLDER, NOT A REAL AUTOSCALER
+# -------------------------------------------------------------------------------------------------
+# `minReplicas: 2` is the entire point. The CPU metric exists because an autoscaling/v2 HPA needs a
+# metric to be a valid object, not because coredns is expected to scale on load: measured via
+# metrics-server, the two pods use **5m and 4m** against a **100m** request — ~5% utilisation, so
+# the 80% target will never be approached and the HPA will sit at `minReplicas` indefinitely.
+#
+# The CPU request is what makes this legal: coredns ships `requests: {cpu: 100m, memory: 70Mi}`
+# (measured), and a Resource/Utilization metric is meaningless without a request. metrics-server is
+# installed as a k3s addon and verified serving (`kubectl top pod -l k8s-app=kube-dns` returns
+# figures), so the metric resolves rather than leaving the HPA with `ScalingActive=False`.
+#
+# `maxReplicas: 3` = the node count. coredns' pod anti-affinity prefers one pod per node, so a
+# fourth replica would add no failure-domain coverage; the ceiling exists so a metrics glitch can
+# never balloon DNS pods across the cluster.
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: coredns
+  # kube-system, because that is where k3s puts coredns. This is the only object this component
+  # places outside a namespace it owns, and it is additive: it creates nothing in kube-system and
+  # mutates only the coredns Deployment's scale subresource.
+  namespace: kube-system
+  labels:
+    app.kubernetes.io/name: coredns
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: coredns
+  minReplicas: 2
+  maxReplicas: 3
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          # Deliberately high. See "floor-holder" above: this must not scale on normal DNS load.
+          averageUtilization: 80
+  behavior:
+    scaleDown:
+      # 10 minutes. DNS is the worst thing in the cluster to flap: a scale-down races in-flight
+      # queries and every client's negative cache. The HPA should be reluctant in this direction.
+      stabilizationWindowSeconds: 600
+      policies:
+        - type: Pods
+          value: 1
+          periodSeconds: 600
+    scaleUp:
+      # Prompt in the direction that restores redundancy — this is the path taken after a k3s
+      # restart has re-staged `replicas: 1`.
+      stabilizationWindowSeconds: 0
+      policies:
+        - type: Pods
+          value: 2
+          periodSeconds: 60
@@ -7,3 +7,7 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
  - coredns-custom.yaml
+  # HA floor for the coredns Deployment itself — a separate concern from the split-horizon server
+  # block above, and deliberately an HPA rather than a replica edit: k3s owns that Deployment via
+  # its own deploy controller and re-stages `replicas: 1` on restart. hpa.yaml has the reasoning.
+  - hpa.yaml
@@ -154,6 +154,74 @@ NEW client, a new protocol mapper or a changed scope still needs the realm impor
 (it will not on its own) or a deliberate admin-API/`kcadm` change. `Done=True` is never evidence that
 a realm edit landed.

+## Passkeys (WebAuthn Passwordless) — DECLARED IN GIT, NOT YET IN THE REALM (2026-10-17)
+
+`keycloak-realm-import.yaml` now declares passkey login: the realm's **WebAuthn Passwordless**
+policy (`webAuthnPolicyPasswordless*`), and a `browser-mfa` flow that offers a passkey as an
+**ALTERNATIVE** beside the password form. Design decisions and their reasoning are in the manifest
+comments, not repeated here. The headline choices:
+
+| Decision | Value | One-line reason |
+|---|---|---|
+| Additive or replacing? | **Additive** — passkey *or* password | A misfiring mandatory flow locks the single operator out of every SSO app *and* kubectl |
+| Enrolment | **Optional**, never a default action | Same reason; `webauthn-register-passwordless` is already enabled-not-forced by default |
+| Relying-party ID | `${BASE_DOMAIN}` (not `keycloak.${BASE_DOMAIN}`) | An unre-keyable credential must not be bound to a hostname that can move |
+| User verification | `required` | Without it, mere possession of an unlocked device is a complete login |
+| Resident key | `Yes` | A non-discoverable credential is a second factor, not a passkey |
+| OTP after a passkey? | **No** — conditional OTP stays on the password branch | A UV-required passkey is already two factors, and a phishing-resistant pair at that |
+
+### This change does NOT reach the live realm. At all.
+
+Same one-shot failure this file already documents twice above, third field over. Measured on prod
+2026-10-17:
+
+```
+$ kubectl --context k3s-prod -n keycloak get keycloakrealmimport homelab -o jsonpath='{.status}'
+{"conditions":[{"status":"True","type":"Done"},{"status":"False","type":"Started"},
+               {"status":"False","type":"HasErrors"}]}
+```
+
+`Done=True` / `Started=False` — the import has completed and **will not re-run**, so a policy block
+and three new sub-flows added to this file change nothing about how anyone logs in. The
+client-secret/client-URL reconciler does **not** close this gap and was never meant to: its hard
+endpoint allow-list makes `/authentication` unreachable **by design** (see the table above), and
+realm-level policy fields are not client fields. This is exactly the "a NEW client, a new protocol
+mapper or a changed scope still needs the realm import to actually re-run" case named above.
+
+**So the manifest is the declared source of truth and a DR-rebuild input, and nothing more, until
+an operator applies it by hand.** Two paths, both operator actions:
+
+1. **Admin console (expected path).** *Authentication → Policies → WebAuthn Passwordless Policy*
+   for the policy block, then *Authentication → Flows → browser-mfa* to rebuild the executions to
+   match the manifest. The flow edit is the fiddly half: split the existing Username Password Form
+   into Username Form + Password Form and add the two sub-flows exactly as declared.
+2. **A deliberate re-import.** Deleting and recreating the `KeycloakRealmImport` re-runs it against
+   the **existing** realm. Do not reach for this casually — it is the operation whose failure mode
+   is the 2026-09-06 total SSO outage documented above, and it has not been rehearsed here.
+
+Either way the realm is then configured by hand and git is only the record of intent, which is a
+live exception to R-IDP-03 (config as code) — not a new one, but one more instance of it.
+
+### Verifying it actually works (nobody has, as of 2026-10-17)
+
+No passkey has been enrolled and no browser has been pointed at this. The checks that would prove
+it, in order:
+
+```sh
+# 1. the policy is live (RP ID must read as the base domain, NOT the keycloak host, NOT a URL)
+#    Authentication -> Policies -> WebAuthn Passwordless Policy, in the admin console.
+# 2. enrol: account console (https://keycloak.${BASE_DOMAIN}/realms/homelab/account) -> Signing in
+#    -> Passwordless -> set up. A browser/OS passkey prompt must appear; if it does not, the RP ID
+#    is wrong for the origin and NOTHING will say so.
+# 3. log in: a fresh private window to any SSO-gated app. Expect username screen, then a passkey
+#    prompt. A platform-admin must NOT be asked for TOTP on this path.
+# 4. regression (the important one): a user with NO passkey must still get the password screen,
+#    and a platform-admin must still be asked for TOTP there.
+```
+
+A failed passkey ceremony is usually silent in the server log — the browser refuses before Keycloak
+is involved — so step 2 failing with no log entry is the expected signature of a wrong RP ID.
+
 ## Exceptions that keep native auth (do not force SSO) — ADR-0014

 Plex/Seerr (Plex auth), Minecraft (Mojang/Microsoft), UniFi (native).
@@ -74,6 +74,142 @@ spec:
    bruteForceProtected: true
    permanentLockout: false
    sslRequired: external
+    # ===========================================================================================
+    # PASSKEYS — the WebAuthn PASSWORDLESS policy (R-IDP-04). 2026-10-17.
+    # ===========================================================================================
+    # Read this together with the browser-mfa flow at the bottom of the file: THIS block decides
+    # what a passkey must BE, the FLOW decides when one is OFFERED. Keycloak keeps TWO independent
+    # WebAuthn policies per realm and they are not interchangeable:
+    #
+    #   webAuthnPolicy*             -> the TWO-FACTOR policy, consumed by the `webauthn-authenticator`
+    #                                  authenticator (a security key presented AFTER a password).
+    #   webAuthnPolicyPasswordless* -> the PASSWORDLESS policy, consumed by
+    #                                  `webauthn-authenticator-passwordless` (a passkey presented
+    #                                  INSTEAD of a password). This is the one passkeys use.
+    #
+    # Setting the wrong family is a silent no-op: the passwordless authenticator reads
+    # getWebAuthnPolicyPasswordless() only (WebAuthnPasswordlessAuthenticator.getWebAuthnPolicy),
+    # so a policy written into the two-factor fields is simply never consulted by a passkey login.
+    # Only the passwordless family is declared here; the two-factor family is deliberately left at
+    # Keycloak's defaults because nothing in this realm uses `webauthn-authenticator` — TOTP
+    # (auth-otp-form) is the second factor for platform-admins, see the flow section.
+    #
+    # ADDITIVE AND OPTIONAL — THE DECISION THIS BLOCK EXISTS TO MAKE
+    # -------------------------------------------------------------
+    # Passkeys are offered ALONGSIDE the password, never instead of it, and enrolment is NOT forced.
+    # This is a single-operator homelab whose IdP gates Grafana, Gitea, Nextcloud, Headlamp,
+    # Semaphore, PiHole, Crafty, the *arr stack AND kubectl itself (the `kubernetes` client below).
+    # A mandatory passkey flow that misfires is therefore not an inconvenience, it is a total
+    # lock-out from the whole platform AND from the cluster API in one step — and the only repair
+    # paths left would be the Keycloak bootstrap admin and the break-glass cert kubeconfig. The
+    # expected gain from forcing enrolment (one human stops typing a password) is small; the
+    # expected loss is the platform. So: additive, optional, and password login keeps working for
+    # every user who never enrols.
+    #
+    # Concretely that means: no `requiredActions` block is declared anywhere in this file (see the
+    # long note in the flow section for why declaring one would be actively DANGEROUS), and the
+    # passkey step sits as an ALTERNATIVE beside the password form rather than ahead of it.
+    #
+    # RELYING-PARTY ID — THE FIELD THAT SILENTLY BREAKS EVERY PASSKEY IF IT IS WRONG
+    # ------------------------------------------------------------------------------
+    # The RP ID is baked into every credential at enrolment and can never be changed afterwards:
+    # a passkey created under one RP ID is unusable under another, with no error the user can act
+    # on — the browser simply reports that no credential is available. It is also browser-enforced,
+    # so it cannot be "fixed" server-side: per WebAuthn, the RP ID must be equal to, or a
+    # registrable-domain suffix of, the origin's effective domain. Keycloak is served at
+    # keycloak.<BASE_DOMAIN> (httproute.yaml, and the Keycloak CR's hostname), so the legal choices
+    # are keycloak.<BASE_DOMAIN>, <BASE_DOMAIN>, or the registrable domain one level up. It is NOT
+    # the full URL and NOT a scheme — "https://..." here would fail every ceremony.
+    #
+    # We choose BASE_DOMAIN, the shared platform suffix, NOT the keycloak host, for one concrete
+    # reason drawn from this repo's own history: a credential that cannot be re-keyed must not be
+    # bound to a name that can move. The oauth2-proxy client below ALREADY declares a redirect URI
+    # on auth.<BASE_DOMAIN>, i.e. this platform already contemplates serving auth on a second
+    # hostname; and the client-URL reconciler exists precisely because moving a hostname in git
+    # silently fails to reach the realm (see README, "Client URLs: the same one-shot failure").
+    # Binding passkeys to the keycloak subdomain would mean that relocating Keycloak invalidates
+    # every enrolled passkey; binding them to BASE_DOMAIN survives it. The cost is scope: any
+    # future WebAuthn relying party under this base domain could assert the same RP ID. In a
+    # homelab where every such party is already behind THIS IdP that is not a trust boundary worth
+    # buying. Note the residual, unavoidable risk: changing BASE_DOMAIN itself invalidates every
+    # passkey, which is a re-enrolment, not a repair.
+    #
+    # Written as the cluster-var so it is substituted by the same Flux postBuild pass, with the same
+    # value, as every hostname in this file — there is no second place the domain is decided.
+    webAuthnPolicyPasswordlessRpId: ${BASE_DOMAIN}
+    # The human-readable name the browser/OS shows in the passkey prompt and stores beside the
+    # credential ("Save a passkey for Homelab SSO?"). Matches the realm displayName above so the
+    # OS keychain entry is recognisable. It is also load-bearing on the UPDATE path: Keycloak's
+    # updateRealm applies the passwordless policy ONLY when this field is non-empty
+    # (DefaultExportImportManager line ~842), so an admin-API realm update that omits it drops the
+    # whole policy silently.
+    webAuthnPolicyPasswordlessRpEntityName: "Homelab SSO"
+    # ES256 then RS256 — exactly Keycloak's own DEFAULT_POLICY, declared explicitly rather than
+    # inherited so the realm's crypto is auditable from git. ES256 is what every platform
+    # authenticator (Touch ID/Face ID, Windows Hello, Android) and every FIDO2 key produces;
+    # RS256 is the fallback for older Windows Hello TPM-backed credentials. EdDSA/Ed25519 is
+    # deliberately NOT offered: authenticator and browser support is uneven, and an authenticator
+    # that picks an algorithm the verifier handles badly fails at enrolment, which is the worst
+    # moment to discover it. Order is a preference list, not an allow-list ordering requirement.
+    webAuthnPolicyPasswordlessSignatureAlgorithms:
+      - ES256
+      - RS256
+    # DISCOVERABLE CREDENTIAL REQUIRED. "Yes" is a Keycloak sentinel, not a boolean, and the login
+    # theme compares it as the literal string: webauthnRegister.js maps 'Yes' to
+    # authenticatorSelection.requireResidentKey=true and ANY other non-sentinel value to false.
+    # This is not optional for passkeys — a non-discoverable credential cannot be found by the
+    # browser without the server first naming it, so it is a second factor, not a passkey.
+    # (Keycloak 26.0.6 emits only the LEGACY requireResidentKey member, not the newer
+    # residentKey:"required"; per WebAuthn L2 the client maps requireResidentKey=true onto
+    # residentKey="required", so discoverable credentials are genuinely requested — but it also
+    # means this policy cannot express residentKey:"preferred" at all.)
+    webAuthnPolicyPasswordlessRequireResidentKey: "Yes"
+    # USER VERIFICATION REQUIRED. The authenticator must verify the human (biometric or PIN) and
+    # say so in the assertion. This is the field that makes a passkey login at least as strong as
+    # the password it replaces: with verification merely "preferred", possession of an unlocked
+    # phone or an unattended security key would be a COMPLETE login to every SSO-gated app — a
+    # single-factor possession check, strictly weaker than the password+TOTP path beside it.
+    # Required makes the passkey branch inherently two-factor (something you have + something you
+    # are/know), which is the premise the flow section relies on when it does NOT ask a
+    # passkey-authenticated platform-admin for TOTP as well.
+    webAuthnPolicyPasswordlessUserVerificationRequirement: required
+    # "not specified" is Keycloak's sentinel for "either kind of authenticator"
+    # (Constants.DEFAULT_WEBAUTHN_POLICY_NOT_SPECIFIED; the theme JS omits the WebAuthn member
+    # entirely when it sees this exact string). Deliberately NOT narrowed: "platform" would reject
+    # every YubiKey and every phone used as a cross-device passkey, and "cross-platform" would
+    # reject Touch ID and Windows Hello — i.e. either choice silently halves the usable hardware.
+    # The operator should be able to enrol a laptop AND a phone AND a hardware key.
+    webAuthnPolicyPasswordlessAuthenticatorAttachment: "not specified"
+    # ATTESTATION: none. Requesting "direct" would hand Keycloak an attestation statement it has
+    # no trust anchors to validate here (no metadata service is configured) and nothing to compare
+    # it against, since the AAGUID allow-list below is deliberately empty — so the statement would
+    # be collected, unverifiable, and would add an extra "share model information?" consent prompt
+    # on Safari/iOS for no security gain. Attestation is how you ENFORCE an approved-hardware list;
+    # we do not have one, so asking for it is cost without benefit.
+    webAuthnPolicyPasswordlessAttestationConveyancePreference: none
+    # Empty = accept any authenticator model. An AAGUID allow-list is a hardware whitelist: it
+    # would have to be maintained by hand, and every new phone, laptop or key the operator buys
+    # would be rejected at enrolment with a message that does not explain itself. It is also moot
+    # while attestation is "none" (above) — with no attestation statement there is no trustworthy
+    # AAGUID to match against in the first place.
+    webAuthnPolicyPasswordlessAcceptableAaguids: []
+    # Ceremony timeout in SECONDS (the login theme multiplies by 1000; 0 means "send no timeout and
+    # let the browser decide"). 300s is chosen over a tighter value because the slowest LEGITIMATE
+    # path is the cross-device hybrid flow — Keycloak renders a QR code, the operator unlocks a
+    # phone, scans it, and completes a biometric check — which routinely takes over a minute. A
+    # 60-120s timeout looks tidy and converts that flow into an unexplained failure. Browsers clamp
+    # this value (Chrome to at most 10 minutes), so 300 is honoured rather than reinterpreted.
+    webAuthnPolicyPasswordlessCreateTimeout: 300
+    # Send the user's existing passkeys as excludeCredentials at enrolment, so re-enrolling an
+    # authenticator the user already registered is refused by the authenticator itself instead of
+    # producing a second, indistinguishable credential in the account console. Cheap, and it keeps
+    # "which passkey is which" answerable — which matters when the recovery story is "delete the
+    # lost one".
+    webAuthnPolicyPasswordlessAvoidSameAuthenticatorRegister: true
+    # webAuthnPolicyPasswordlessExtraOrigins is intentionally NOT set. It exists to admit non-web
+    # origins (native app facet IDs, e.g. android:apk-key-hash:...). Every ceremony here happens in
+    # a browser on Keycloak's own origin, which is already covered by the RP ID above; adding
+    # origins is only ever a widening of who may ask for these credentials.
    # --- Authorization model (R-IDP-06): groups drive access; platform-admins carry a realm role. ---
    roles:
      realm:
@@ -528,14 +664,105 @@ spec:
              "access.token.claim": "true"
              "userinfo.token.claim": "true"
              "claim.name": groups
-    # --- MFA for platform-admins (R-IDP-04): a browser flow whose OTP step is CONDITIONAL on the
-    #     platform-admin role. Non-admins log in without OTP; platform-admins must enroll/present TOTP.
-    #     Set as the realm browserFlow below. VERIFY at bring-up (see runbook): a malformed flow fails
-    #     the whole import — if so, the fallback is to comment this block + browserFlow and configure
-    #     the conditional-OTP-by-role flow via the admin console. ---
+    # ===========================================================================================
+    # MFA for platform-admins (R-IDP-04) + PASSKEY login (2026-10-17). The realm browserFlow is
+    # bound to browser-mfa at the bottom of this file.
+    # ===========================================================================================
+    # Non-admins log in without OTP; platform-admins must enroll/present TOTP. VERIFY at bring-up
+    # (see runbook): a malformed flow fails the whole import — if so, the fallback is to comment
+    # this block + browserFlow and configure the flow via the admin console.
+    #
+    # THE SHAPE, AND WHY IT IS THIS SHAPE
+    # -----------------------------------
+    #   browser-mfa                           (top level, bound as browserFlow)
+    #     auth-cookie                     ALTERNATIVE   already-authenticated SSO cookie
+    #     identity-provider-redirector    ALTERNATIVE   (no IdPs configured; kept for parity)
+    #     browser-mfa-forms               ALTERNATIVE   the interactive path:
+    #       auth-username-form              REQUIRED      WHO are you (no password yet)
+    #       browser-mfa-passkey-or-password REQUIRED      ...and PROVE it, one of two ways:
+    #         webauthn-authenticator-passwordless  ALTERNATIVE   a passkey, or
+    #         browser-mfa-password-and-otp         ALTERNATIVE   the password path:
+    #           auth-password-form                   REQUIRED      password, then
+    #           browser-mfa-conditional-otp          CONDITIONAL   TOTP iff platform-admin
+    #
+    # WHY THE USERNAME/PASSWORD SCREEN HAD TO BE SPLIT IN TWO. The previous flow used the combined
+    # `auth-username-password-form`, which collects both on one page. A passkey branch cannot live
+    # behind that: the server must know WHICH user is logging in before it can decide whether a
+    # passkey is even available, and the combined form has already taken the password by the time
+    # it knows. So it is replaced by the `auth-username-form` / `auth-password-form` pair — the
+    # same decomposition Keycloak's own passwordless recipe uses. THIS IS A VISIBLE UX CHANGE FOR
+    # EVERY USER, passkey or not: login becomes two screens (username, then password) instead of
+    # one. That cost is accepted deliberately — it is the enabling change, it is what Google and
+    # Microsoft logins already do, and the alternative (below) is worse.
+    #
+    # WHY NOT USERNAMELESS ("just tap your passkey", no username screen at all). Keycloak 26.0.6
+    # does support it: WebAuthnPasswordlessAuthenticator.requiresUser() returns FALSE, so the
+    # authenticator can legally run as a first step with no user in context. We deliberately do not
+    # do that, because of how the flow engine then behaves. In DefaultAuthenticationFlow the
+    # "does this user actually have this credential?" guard sits INSIDE the requiresUser() branch;
+    # with requiresUser() false and no user yet set, the engine skips that guard and simply invokes
+    # the authenticator. A passkey execution placed before the username form is therefore offered
+    # to EVERYONE, so every login — including every password-only user and every family member who
+    # will never own a passkey — would open on a passkey prompt they must dismiss. That is the
+    # opposite of additive. Keeping the passkey step AFTER auth-username-form means a user is in
+    # context, which is what makes the graceful degradation below actually work.
+    #
+    # WHY THE PASSKEY BRANCH DEGRADES CLEANLY TO A PASSWORD (the property the whole "additive"
+    # claim rests on). With a user in context, the engine takes the non-requiresUser branch and
+    # raises CREDENTIAL_SETUP_REQUIRED when the user has no credential of this type and the
+    # authenticator's factory does not allow self-setup — and WebAuthnPasswordlessAuthenticatorFactory
+    # .isUserSetupAllowed() is false, and the authenticator is a CredentialValidator, so both
+    # conditions hold. That exception is raised INSIDE the ALTERNATIVE loop, which catches it,
+    # marks the execution ATTEMPTED and proceeds to the next alternative. Net effect: a user with
+    # no passkey never sees a passkey screen and lands on the password form; a user WITH one gets
+    # the passkey screen and keeps the password as a "Try another way" option. Note that for a
+    # user holding BOTH, which screen appears FIRST is decided by Keycloak's authentication
+    # selection list (the user's own credential ordering), not by the priorities below.
+    #
+    # WHY A PASSKEY LOGIN IS NOT ALSO ASKED FOR TOTP. browser-mfa-conditional-otp hangs off the
+    # PASSWORD branch only, so a platform-admin who authenticates with a passkey is not challenged
+    # for TOTP. That is intentional, and it rests on the policy above: userVerification is
+    # `required`, so the authenticator has already proved possession of hardware AND verified the
+    # human (biometric or PIN) in one phishing-resistant, origin-bound ceremony. Stacking TOTP on
+    # top would add a replayable, phishable shared secret to a credential that is neither, for
+    # friction on every login. If a future operator disagrees, the change is small and local: move
+    # the browser-mfa-conditional-otp reference out of browser-mfa-password-and-otp and into
+    # browser-mfa-passkey-or-password's parent as a REQUIRED step, so it applies to both branches.
+    #
+    # WHY THERE IS NO `requiredActions` BLOCK IN THIS FILE — DO NOT ADD ONE
+    # --------------------------------------------------------------------
+    # Enrolment uses Keycloak's `webauthn-register-passwordless` required action, and the obvious
+    # move is to declare it here. DO NOT. In Keycloak 26.0.6 the realm import treats
+    # requiredActions as REPLACE, NOT MERGE: DefaultExportImportManager.importRealm branches on
+    # `if (rep.getRequiredActions() != null)` and, when the representation declares ANY, imports
+    # exactly those plus delete_account — the `else` branch that installs the full default set
+    # (DefaultRequiredActions.addActions) never runs. RealmManager.setupRequiredActions is no
+    # backstop either: it fires only when the realm has ZERO required-action providers.
+    #
+    # So declaring one action would create this realm with that action and delete_account and
+    # NOTHING ELSE — no CONFIGURE_TOTP, no UPDATE_PASSWORD, no VERIFY_EMAIL, no delete_credential,
+    # no UPDATE_PROFILE. The first casualty would be the MFA requirement this very flow enforces:
+    # with CONFIGURE_TOTP unregistered, a platform-admin who does not yet have TOTP could never
+    # enrol one, while auth-otp-form below still demands it — a hard lock-out of every
+    # platform-admin from every SSO-gated app, including Headlamp and kubectl, delivered by a
+    # change whose stated purpose was to ADD a login method.
+    #
+    # And the declaration buys nothing, because the default set ALREADY CONTAINS IT.
+    # DefaultRequiredActions registers `webauthn-register-passwordless` with enabled=true,
+    # defaultAction=false, priority 80, gated on Profile.Feature.WEB_AUTHN — which is Type.DEFAULT
+    # in 26.0.6, i.e. on unless explicitly disabled. enabled=true / defaultAction=false IS the
+    # additive-and-optional posture this change wants: the action exists and can be triggered for
+    # a user on demand, but it is not forced on anyone at next login. Declaring it would restate
+    # the default while deleting ten siblings.
+    #
+    # (The symmetric question for authenticationFlows has the opposite answer, which is why THIS
+    # block is safe: importAuthenticationFlows adds the declared flows and then backfills each
+    # unbound binding — browser, registration, direct grant, reset credentials, client auth, first
+    # broker login, docker auth — from the built-in defaults individually. Declaring flows does not
+    # suppress the built-ins; declaring required actions does suppress them.)
    authenticationFlows:
      - alias: browser-mfa
-        description: "Browser flow with conditional OTP required for platform-admins."
+        description: "Browser flow: passkey or password, with conditional OTP for platform-admins."
        providerId: basic-flow
        topLevel: true
        builtIn: false
@@ -555,13 +782,63 @@ spec:
            priority: 30
            flowAlias: browser-mfa-forms
            userSetupAllowed: false
+      # Identify the user FIRST (username only), then prove it. Both steps are REQUIRED: the
+      # username is never optional, and neither is proving possession of the account.
      - alias: browser-mfa-forms
-        description: "Username/password then conditional OTP."
+        description: "Username, then passkey or password (+ conditional OTP)."
        providerId: basic-flow
        topLevel: false
        builtIn: false
        authenticationExecutions:
-          - authenticator: auth-username-password-form
+          # auth-username-form = Keycloak's "Username Form" (UsernameFormFactory) — resolves the
+          # user WITHOUT taking a password, which is the prerequisite for offering a passkey.
+          # Replaces the previous auth-username-password-form; see the header for the UX cost.
+          - authenticator: auth-username-form
+            authenticatorFlow: false
+            requirement: REQUIRED
+            priority: 10
+            userSetupAllowed: false
+          - authenticatorFlow: true
+            requirement: REQUIRED
+            priority: 20
+            flowAlias: browser-mfa-passkey-or-password
+            userSetupAllowed: false
+      # THE FORK. Two ALTERNATIVEs, so satisfying either one completes the flow. Priority puts the
+      # passkey first for users who have one; users who do not fall through to the password branch
+      # automatically (CREDENTIAL_SETUP_REQUIRED is caught by the ALTERNATIVE loop — see header).
+      - alias: browser-mfa-passkey-or-password
+        description: "A passkey (WebAuthn passwordless), or password with conditional OTP."
+        providerId: basic-flow
+        topLevel: false
+        builtIn: false
+        authenticationExecutions:
+          # webauthn-authenticator-passwordless = "WebAuthn Passwordless Authenticator"
+          # (WebAuthnPasswordlessAuthenticatorFactory). It reads the realm's PASSWORDLESS policy
+          # declared above — NOT the two-factor webAuthnPolicy* family. Keep it ALTERNATIVE: as
+          # REQUIRED it would force a passkey on every user, which is the lock-out this change is
+          # explicitly designed not to create.
+          - authenticator: webauthn-authenticator-passwordless
+            authenticatorFlow: false
+            requirement: ALTERNATIVE
+            priority: 10
+            userSetupAllowed: false
+          - authenticatorFlow: true
+            requirement: ALTERNATIVE
+            priority: 20
+            flowAlias: browser-mfa-password-and-otp
+            userSetupAllowed: false
+      # The unchanged pre-passkey behaviour, relocated intact into the password branch: password,
+      # then TOTP iff the user holds the platform-admin role. Nothing about the OTP condition
+      # changed; it simply no longer sits on the path a passkey login takes.
+      - alias: browser-mfa-password-and-otp
+        description: "Password, then conditional OTP for platform-admins."
+        providerId: basic-flow
+        topLevel: false
+        builtIn: false
+        authenticationExecutions:
+          # auth-password-form = Keycloak's "Password Form" (PasswordFormFactory) — the password
+          # half of the old combined form, now that the username has already been collected.
+          - authenticator: auth-password-form
            authenticatorFlow: false
            requirement: REQUIRED
            priority: 10
@@ -1,99 +0,0 @@
-{
-  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "_comment": "Renovate config — Phase 4 automated updates (ADR-0009, R-UPD-01/02). AS OF 2026-10-17 RENOVATE OWNS BOTH HALVES: Helm chart/dependency bumps AND per-service container image tags. It opens PRs for everything; allowed low-risk classes auto-merge on green CI. The ADR-0009 split that gave image tags to Flux image-automation is formally closed — see .gitea/workflows/renovate.yaml for the three measured reasons (it pushes commits rather than opening PRs, so it bypasses the CLAUDE.md §1 gate; `main` is protected with user_can_push:false and the flux-system GitRepository has no secretRef, so it cannot write anyway; and enabling it would need an in-cluster git WRITE credential for the repo that defines the cluster). image-automation has been commented out at platform/kustomization.yaml:52 since it was authored and the cluster holds zero ImagePolicy/ImageRepository/ImageUpdateAutomation objects, so nothing is being torn down. CONSEQUENCE: the `docker` and `kubernetes` managers, previously disabled ONLY to avoid fighting that controller, are now ENABLED — without them every plain `image: repo/name:tag` line in this repo was maintained by nothing at all, which is how the oauth2-proxy auth sidecars reached 7 minors behind the oauth2-proxy running in the same cluster. RUNNER: .gitea/workflows/renovate.yaml (scheduled daily); platform/endpoint are set there, not here.",
-  "extends": [
-    "config:recommended",
-    ":dependencyDashboard",
-    ":semanticCommits",
-    "helpers:pinGitHubActionDigests"
-  ],
-  "timezone": "America/New_York",
-  "schedule": ["after 3am and before 6am"],
-  "prConcurrentLimit": 5,
-  "prHourlyLimit": 2,
-  "commitMessagePrefix": "chore(deps):",
-  "labels": ["dependencies", "automated-update"],
-  "ignoreUnstable": true,
-  "respectLatest": true,
-  "enabledManagers": ["flux", "kustomize", "helmv3", "kubernetes", "regex", "github-actions"],
-  "flux": {
-    "managerFilePatterns": ["/(^|/)platform/.+\\.ya?ml$/", "/(^|/)apps/.+\\.ya?ml$/"]
-  },
-  "kustomize": {
-    "managerFilePatterns": ["/(^|/)kustomization\\.ya?ml$/"]
-  },
-  "_kubernetes_comment": "ADDED 2026-10-17. The `kubernetes` manager reads plain `image:` fields out of Kubernetes manifests, and it is NOT auto-detected — it only looks at files matched here, which is why this block is as broad as it is. Scope covers every place this repo writes a container image: platform components, the rendered app waves, the ServiceDefinition catalog that generates them, the runbooks web server and the pm-agent job template. `catalog/` matters as much as `apps/`: apps/wave-*/*.yaml are GENERATED by catalog/render.py, so a bump applied only to the rendered output is reverted by the next render and would also fail ci/render-golden.sh. Renovate will raise BOTH, and both must land together.",
-  "kubernetes": {
-    "managerFilePatterns": [
-      "/(^|/)platform/.+\\.ya?ml$/",
-      "/(^|/)platform-config/.+\\.ya?ml$/",
-      "/(^|/)apps/.+\\.ya?ml$/",
-      "/(^|/)catalog/.+\\.ya?ml$/",
-      "/(^|/)runbooks/serving/.+\\.ya?ml$/",
-      "/(^|/)infra/agent/.+\\.ya?ml$/"
-    ]
-  },
-  "customManagers": [
-    {
-      "customType": "regex",
-      "description": "Inline `# renovate: datasource=... depName=...` markers on pinned URLs / version literals (e.g. platform/kubevirt/kustomization.yaml release URLs, ci/versions.env, infra/devcontainer/versions.env).",
-      "managerFilePatterns": [
-        "/(^|/)kustomization\\.ya?ml$/",
-        "/(^|/)versions\\.env$/"
-      ],
-      "matchStrings": [
-        "#\\s*renovate:\\s*datasource=(?<datasource>\\S+)\\s+depName=(?<depName>\\S+)(?:\\s+versioning=(?<versioning>\\S+))?\\s*\\n.*?(?<currentValue>v?[0-9]+\\.[0-9]+\\.[0-9]+)"
-      ],
-      "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
-    }
-  ],
-  "packageRules": [
-    {
-      "description": "Auto-merge the allowed low-risk classes on green CI — no human authoring (R-UPD-02). The Gitea merge gate (make -C ci gate) is the required check.",
-      "matchUpdateTypes": ["minor", "patch", "digest"],
-      "automerge": true,
-      "automergeType": "pr",
-      "platformAutomerge": true
-    },
-    {
-      "description": "MAJOR / potentially-breaking bumps require human review (docs/11 safety rail). Never auto-merged.",
-      "matchUpdateTypes": ["major"],
-      "automerge": false,
-      "addLabels": ["needs-review", "breaking"]
-    },
-    {
-      "description": "Keep the KubeVirt + CDI operator pair on a compatible track — grouped so they bump together (platform/kubevirt/kustomization.yaml).",
-      "matchDepNames": ["kubevirt/kubevirt", "kubevirt/containerized-data-importer"],
-      "groupName": "kubevirt-cdi"
-    },
-    {
-      "description": "Pinned tool versions (ci/versions.env, infra/devcontainer/versions.env) are a deliberate change surface — label but do not auto-merge; a version bump there changes CI reproducibility.",
-      "matchFileNames": ["ci/versions.env", "infra/devcontainer/versions.env"],
-      "automerge": false,
-      "addLabels": ["ci-tooling"]
-    },
-    {
-      "description": "ADDED 2026-10-17. NEVER AUTO-MERGE THE BLAST-RADIUS COMPONENTS, not even a patch. The default rule above auto-merges minor/patch/digest on a green gate, which is right for an app image: a bad Sonarr bump inconveniences one pod. It is wrong for these five, because the gate is a STATIC check — it renders manifests and lints them, it does not boot a node, drain a volume or form an etcd quorum (vars.CLUSTER_AVAILABLE is unset, so L2/L3 conformance does not run in CI at all). So for anything whose failure mode is the CLUSTER rather than a service, a green gate is not evidence and a human must read the changelog. kured is here because it reboots control-plane nodes; longhorn because a storage-engine bump migrates live volume data; cilium because it is the CNI and a bad bump is a total partition (and its version is DUAL-PINNED in infra/ansible/roles/cilium/defaults/main.yml, which Renovate does not see, so the two would silently desync); cloudnative-pg because it drives Postgres switchovers; kube-prometheus-stack because ci/versions.env asserts an exact promtool/Prometheus lockstep and a chart bump that moves Prometheus fails the gate until that file moves with it.",
-      "matchPackageNames": [
-        "kured",
-        "longhorn",
-        "cilium",
-        "cloudnative-pg",
-        "kube-prometheus-stack"
-      ],
-      "automerge": false,
-      "addLabels": ["needs-review", "blast-radius"]
-    }
-  ],
-  "_unmanageable_comment": "WHAT RENOVATE STILL CANNOT FIX, so nobody mistakes a working bot for full coverage. A FLOATING tag has no version to compare, so Renovate skips it silently — it does not pin it and does not warn. As of 2026-10-17 that is: plexinc/pms-docker:latest, lscr.io/linuxserver/jackett:latest, pihole/pihole (NO TAG AT ALL), quay.io/keycloak/keycloak (no tag), nextcloud:31-apache and docker:27-dind. Those must be pinned BY HAND to a concrete version before any automation can maintain them, and until then they drift on every pull with nothing recording what is running. Separately, the HelmRelease minor-locking ranges (9 of 12, e.g. `>=88.0.0 <89.0.0` on kube-prometheus-stack) cap Renovate at patches inside a line it has been told not to leave; raising those ceilings is deliberate per-component work and is NOT part of enabling the bot. Both lists are in decisions/2026-10-17-automated-upgrades.md.",
-  "ignorePaths": [
-    "**/*.example",
-    "**/*.sops.yaml",
-    "conformance/**",
-    "platform/image-automation/per-service/**",
-    "platform/kyverno/tests/**"
-  ],
-  "_ignorePaths_comment": "platform/kyverno/tests/** ADDED 2026-10-17: those Kyverno policy fixtures pin `alpine:latest` and a `conformance-runner:latest`, which are test inputs whose whole point is to be a fixed shape, not software to keep current. `conformance/**` was already ignored for the same reason; this closes the matching hole that enabling the `kubernetes` manager would otherwise have opened.",
-  "_docker_comment": "The `docker` manager (Dockerfiles, docker-compose) and the `kubernetes` manager above were BOTH previously `enabled: false`, solely so Renovate would not fight Flux image-automation over a running tag. That controller was never enabled and never will be here (see _comment), so the only thing those two flags were achieving was leaving every plain `image:` tag in the repo unmanaged. `docker` is left out of enabledManagers because this repo contains no Dockerfile that ships to the cluster; `kubernetes` is now ON and is the one that matters.",
-  "docker": { "enabled": true }
-}
@@ -0,0 +1,187 @@
+// =================================================================================================
+// Renovate configuration — JSON5, so the rationale can live NEXT TO what it explains.
+// =================================================================================================
+// THIS FILE WAS `renovate.json` AND IT WAS INVALID. It carried five `_comment` / `_*_comment`
+// pseudo-comment keys, because JSON has no comments. Renovate REJECTS unknown top-level options, so
+// the whole config failed validation and the first manual run of the workflow ERRORED OUT. Proven
+// with the official validator (`ghcr.io/renovatebot/renovate renovate-config-validator`):
+//
+//   ERROR: Found errors in configuration
+//     Invalid configuration option: _comment
+//     Invalid configuration option: _docker_comment
+//     Invalid configuration option: _ignorePaths_comment
+//     Invalid configuration option: _kubernetes_comment
+//     Invalid configuration option: _unmanageable_comment
+//
+// Renovate discovers `renovate.json5` natively (no RENOVATE_CONFIG_FILE needed, and nothing in
+// .gitea/ or ci/ pins the old filename — only prose in comments), and JSON5 permits real `//`
+// comments. So the fix keeps every word of the original rationale, positioned, instead of
+// flattening it into a `description` string.
+//
+// VALIDATE BEFORE COMMITTING — it is one command and it is the only thing that catches this class:
+//   podman run --rm -v "$PWD/renovate.json5:/tmp/renovate.json5:ro,Z" \
+//     ghcr.io/renovatebot/renovate renovate-config-validator /tmp/renovate.json5
+//
+// NOTE on what was NOT wrong: `enabledManagers` containing bare `regex` was suspected of needing to
+// be `custom.regex`. The validator accepts `regex`, so that suspicion was unfounded and nothing
+// here changes it.
+{  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  // Renovate config — Phase 4 automated updates (ADR-0009, R-UPD-01/02). AS OF 2026-10-17
+  // RENOVATE OWNS BOTH HALVES: Helm chart/dependency bumps AND per-service container image tags.
+  // It opens PRs for everything; allowed low-risk classes auto-merge on green CI. The ADR-0009
+  // split that gave image tags to Flux image-automation is formally closed — see
+  // .gitea/workflows/renovate.yaml for the three measured reasons (it pushes commits rather than
+  // opening PRs, so it bypasses the CLAUDE.md §1 gate; `main` is protected with
+  // user_can_push:false and the flux-system GitRepository has no secretRef, so it cannot write
+  // anyway; and enabling it would need an in-cluster git WRITE credential for the repo that
+  // defines the cluster). image-automation has been commented out at
+  // platform/kustomization.yaml:52 since it was authored and the cluster holds zero
+  // ImagePolicy/ImageRepository/ImageUpdateAutomation objects, so nothing is being torn down.
+  // CONSEQUENCE: the `docker` and `kubernetes` managers, previously disabled ONLY to avoid
+  // fighting that controller, are now ENABLED — without them every plain `image: repo/name:tag`
+  // line in this repo was maintained by nothing at all, which is how the oauth2-proxy auth
+  // sidecars reached 7 minors behind the oauth2-proxy running in the same cluster. RUNNER:
+  // .gitea/workflows/renovate.yaml (scheduled daily); platform/endpoint are set there, not here.
+  "extends": ["config:recommended", ":dependencyDashboard", ":semanticCommits", "helpers:pinGitHubActionDigests"],
+  "timezone": "America/New_York",
+  "schedule": ["after 3am and before 6am"],
+  "prConcurrentLimit": 5,
+  "prHourlyLimit": 2,
+  "commitMessagePrefix": "chore(deps):",
+  "labels": ["dependencies", "automated-update"],
+  "ignoreUnstable": true,
+  "respectLatest": true,
+  "enabledManagers": ["flux", "kustomize", "helmv3", "kubernetes", "regex", "github-actions"],
+  "flux": {
+    "managerFilePatterns": [
+      "/(^|/)platform/.+\\.ya?ml$/",
+      "/(^|/)apps/.+\\.ya?ml$/"
+    ]
+  },
+  "kustomize": {
+    "managerFilePatterns": [
+      "/(^|/)kustomization\\.ya?ml$/"
+    ]
+  },
+  // ADDED 2026-10-17. The `kubernetes` manager reads plain `image:` fields out of Kubernetes
+  // manifests, and it is NOT auto-detected — it only looks at files matched here, which is why
+  // this block is as broad as it is. Scope covers every place this repo writes a container image:
+  // platform components, the rendered app waves, the ServiceDefinition catalog that generates
+  // them, the runbooks web server and the pm-agent job template. `catalog/` matters as much as
+  // `apps/`: apps/wave-*/*.yaml are GENERATED by catalog/render.py, so a bump applied only to the
+  // rendered output is reverted by the next render and would also fail ci/render-golden.sh.
+  // Renovate will raise BOTH, and both must land together.
+  "kubernetes": {
+    "managerFilePatterns": [
+      "/(^|/)platform/.+\\.ya?ml$/",
+      "/(^|/)platform-config/.+\\.ya?ml$/",
+      "/(^|/)apps/.+\\.ya?ml$/",
+      "/(^|/)catalog/.+\\.ya?ml$/",
+      "/(^|/)runbooks/serving/.+\\.ya?ml$/",
+      "/(^|/)infra/agent/.+\\.ya?ml$/"
+    ]
+  },
+  "customManagers": [
+    {
+      "customType": "regex",
+      "description": "Inline `# renovate: datasource=... depName=...` markers on pinned URLs / version literals (e.g. platform/kubevirt/kustomization.yaml release URLs, ci/versions.env, infra/devcontainer/versions.env).",
+      "managerFilePatterns": [
+        "/(^|/)kustomization\\.ya?ml$/",
+        "/(^|/)versions\\.env$/"
+      ],
+      "matchStrings": [
+        "#\\s*renovate:\\s*datasource=(?<datasource>\\S+)\\s+depName=(?<depName>\\S+)(?:\\s+versioning=(?<versioning>\\S+))?\\s*\\n.*?(?<currentValue>v?[0-9]+\\.[0-9]+\\.[0-9]+)"
+      ],
+      "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
+    }
+  ],
+  "packageRules": [
+    {
+      "description": "Auto-merge the allowed low-risk classes on green CI \u2014 no human authoring (R-UPD-02). The Gitea merge gate (make -C ci gate) is the required check.",
+      "matchUpdateTypes": [
+        "minor",
+        "patch",
+        "digest"
+      ],
+      "automerge": true,
+      "automergeType": "pr",
+      "platformAutomerge": true
+    },
+    {
+      "description": "MAJOR / potentially-breaking bumps require human review (docs/11 safety rail). Never auto-merged.",
+      "matchUpdateTypes": [
+        "major"
+      ],
+      "automerge": false,
+      "addLabels": [
+        "needs-review",
+        "breaking"
+      ]
+    },
+    {
+      "description": "Keep the KubeVirt + CDI operator pair on a compatible track \u2014 grouped so they bump together (platform/kubevirt/kustomization.yaml).",
+      "matchDepNames": [
+        "kubevirt/kubevirt",
+        "kubevirt/containerized-data-importer"
+      ],
+      "groupName": "kubevirt-cdi"
+    },
+    {
+      "description": "Pinned tool versions (ci/versions.env, infra/devcontainer/versions.env) are a deliberate change surface \u2014 label but do not auto-merge; a version bump there changes CI reproducibility.",
+      "matchFileNames": [
+        "ci/versions.env",
+        "infra/devcontainer/versions.env"
+      ],
+      "automerge": false,
+      "addLabels": [
+        "ci-tooling"
+      ]
+    },
+    {
+      "description": "ADDED 2026-10-17. NEVER AUTO-MERGE THE BLAST-RADIUS COMPONENTS, not even a patch. The default rule above auto-merges minor/patch/digest on a green gate, which is right for an app image: a bad Sonarr bump inconveniences one pod. It is wrong for these five, because the gate is a STATIC check \u2014 it renders manifests and lints them, it does not boot a node, drain a volume or form an etcd quorum (vars.CLUSTER_AVAILABLE is unset, so L2/L3 conformance does not run in CI at all). So for anything whose failure mode is the CLUSTER rather than a service, a green gate is not evidence and a human must read the changelog. kured is here because it reboots control-plane nodes; longhorn because a storage-engine bump migrates live volume data; cilium because it is the CNI and a bad bump is a total partition (and its version is DUAL-PINNED in infra/ansible/roles/cilium/defaults/main.yml, which Renovate does not see, so the two would silently desync); cloudnative-pg because it drives Postgres switchovers; kube-prometheus-stack because ci/versions.env asserts an exact promtool/Prometheus lockstep and a chart bump that moves Prometheus fails the gate until that file moves with it.",
+      "matchPackageNames": [
+        "kured",
+        "longhorn",
+        "cilium",
+        "cloudnative-pg",
+        "kube-prometheus-stack"
+      ],
+      "automerge": false,
+      "addLabels": [
+        "needs-review",
+        "blast-radius"
+      ]
+    }
+  ],
+  // WHAT RENOVATE STILL CANNOT FIX, so nobody mistakes a working bot for full coverage. A
+  // FLOATING tag has no version to compare, so Renovate skips it silently — it does not pin it
+  // and does not warn. As of 2026-10-17 that is: plexinc/pms-docker:latest,
+  // lscr.io/linuxserver/jackett:latest, pihole/pihole (NO TAG AT ALL), quay.io/keycloak/keycloak
+  // (no tag), nextcloud:31-apache and docker:27-dind. Those must be pinned BY HAND to a concrete
+  // version before any automation can maintain them, and until then they drift on every pull with
+  // nothing recording what is running. Separately, the HelmRelease minor-locking ranges (9 of 12,
+  // e.g. `>=88.0.0 <89.0.0` on kube-prometheus-stack) cap Renovate at patches inside a line it
+  // has been told not to leave; raising those ceilings is deliberate per-component work and is
+  // NOT part of enabling the bot. Both lists are in decisions/2026-10-17-automated-upgrades.md.
+  // platform/kyverno/tests/** ADDED 2026-10-17: those Kyverno policy fixtures pin `alpine:latest`
+  // and a `conformance-runner:latest`, which are test inputs whose whole point is to be a fixed
+  // shape, not software to keep current. `conformance/**` was already ignored for the same
+  // reason; this closes the matching hole that enabling the `kubernetes` manager would otherwise
+  // have opened.
+  "ignorePaths": [
+    "**/*.example",
+    "**/*.sops.yaml",
+    "conformance/**",
+    "platform/image-automation/per-service/**",
+    "platform/kyverno/tests/**"
+  ],
+  // The `docker` manager (Dockerfiles, docker-compose) and the `kubernetes` manager above were
+  // BOTH previously `enabled: false`, solely so Renovate would not fight Flux image-automation
+  // over a running tag. That controller was never enabled and never will be here (see _comment),
+  // so the only thing those two flags were achieving was leaving every plain `image:` tag in the
+  // repo unmanaged. `docker` is left out of enabledManagers because this repo contains no
+  // Dockerfile that ships to the cluster; `kubernetes` is now ON and is the one that matters.
+  "docker": {
+    "enabled": true
+  }
+}
@@ -0,0 +1,162 @@
+# cluster-maintenance-shutdown — powering the whole cluster off, and back on
+
+**Operator procedure, not an alert page.** Nothing links here from an alert.
+**Script:** `infra/maintenance/quiesce.sh` (`quiesce` | `resume` | `status`)
+**Related:** `/runbooks/update-rollback` is for rolling node work where the cluster stays up. This
+page is for taking **all three nodes down at once**.
+
+First written after the 2026-10-17 UPS move, which was improvised live because no procedure
+existed — `infra/cluster.sh stop` is `virsh`-based and only ever applied to the decommissioned dev
+cluster, so it does nothing for these three baremetal nodes.
+
+## Why you cannot just run `shutdown -h`
+
+You mostly can now, and could not before.
+
+Until 2026-10-17 **kubelet graceful node shutdown was unconfigured on every prod node**, so systemd
+stopped k3s, containerd went with it, and every pod was SIGKILLed where it stood — 9 Postgres
+instances mid-checkpoint, the UniFi VM, and 25 attached Longhorn volumes.
+`roles/k3s_server` now sets `shutdown-grace-period` (and, critically, the
+`InhibitDelayMaxSec` logind cap that actually enforces it — without that systemd stops waiting
+after 5s and the drain is silently truncated). A plain reboot of one node is therefore safe.
+
+**A planned whole-cluster shutdown still wants `quiesce`**, for three things the kubelet's drain
+does not do:
+
+1. **The UniFi VM needs an ACPI guest shutdown**, not an eviction. KubeVirt does that on
+   `running: false`; an eviction is a power cut to the guest.
+2. **CloudNativePG wants hibernation**, not pod deletion — and hibernation is **imperative** state
+   that Flux will neither set nor clear.
+3. **Draining three nodes one at a time makes pods reschedule onto the survivors**, churning
+   Longhorn replicas for no reason when everything is going down anyway. Scaling in place avoids it.
+
+## The hazard that bit us — read this before scaling anything by hand
+
+**A StatefulSet can carry `persistentVolumeClaimRetentionPolicy.whenScaled: Delete`, and scaling it
+to 0 then DELETES its PVCs and their Longhorn volumes.**
+
+On 2026-10-17 the hand-rolled quiesce scaled `monitoring/loki` (which has that policy) to 0, and
+`storage-loki-0` was deleted outright. Loki stores with `type: filesystem`, so that PVC was the only
+copy. Its 72h retention bounded the loss to a rolling window — nothing about the *mechanism* is
+bounded. The only visible symptom was the Longhorn volume count going 25 → 24, which was first
+misread as a miscount.
+
+`quiesce.sh` now refuses to scale any such StatefulSet, leaves it running, and tells you which
+volumes to expect `degraded` on restart. **If you quiesce by hand, check the policy first:**
+
+```bash
+kubectl --context k3s-prod get statefulset -A \
+  -o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,WHEN_SCALED:.spec.persistentVolumeClaimRetentionPolicy.whenScaled'
+```
+
+A hard-detached volume comes back `degraded` and rebuilds itself automatically. That is a vastly
+better outcome than a deleted one — take the rebuild.
+
+## Shutting down
+
+Run everything through the pinned toolbox; it supplies `kubectl` and the context.
+
+```bash
+# 0. Look before you leap. Refuses to proceed if any Longhorn volume is unhealthy —
+#    powering off on top of a degraded volume is how one replica becomes zero.
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh status'
+
+# 1. Quiesce: suspend Flux, ACPI-stop the VM, hibernate Postgres, scale down every
+#    PVC-holding workload (NFS consumers first, PiHole last), wait for detach.
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh quiesce'
+```
+
+**Expect DNS to stop** when PiHole scales down — it is the LAN resolver. `kubectl` is unaffected
+because the kubeconfig points at the kube-vip IP `192.168.2.9`, not a name.
+
+```bash
+# 2. Power the nodes off. Inside the devcontainer, which holds the become password.
+./infra/devcontainer/dev.sh run bash -c \
+  'cd /work/infra/ansible && ansible -i inventory/hosts.ini k3s_prod -b \
+     -m shell -a "shutdown -h +1 \"maintenance\""'
+```
+
+`+1` gives Ansible time to disconnect cleanly. The group resolves to all three nodes; confirm with
+`--list-hosts` if you want to see them first.
+
+```bash
+# 3. Confirm they are actually down before touching anything else.
+for h in 192.168.2.10 192.168.2.11 192.168.2.12; do ping -c1 -W2 $h >/dev/null && echo "$h UP" || echo "$h down"; done
+```
+
+**Then, in this order and not before:**
+
+| # | Machine | How |
+|---|---|---|
+| 4 | **TrueNAS** `192.168.2.30` | **Web UI only.** Not in the ansible inventory, and SSH is **refused** (service disabled). `https://192.168.2.30` → power icon → Shut Down. Safe once the nodes are down, because every NFS consumer (`plex-media`, `*-media`, `qbittorrent-downloads`, `nextcloud-legacy-archive`) is already scaled to zero and nothing holds a hard mount. |
+| 5 | **Router / switch** | Last. |
+
+TrueNAS must go **after** the k3s nodes: a hard NFS mount on a live node wedges kubelet in
+D-state (`/runbooks/nfs-export-latency`, and the load-average symptom in the 2026-10-?? note).
+
+## Bringing it back
+
+**Power on in the reverse order: router/switch → TrueNAS → all three nodes together.** etcd needs
+2 of 3 for quorum, so start the nodes as a group rather than one at a time.
+
+```bash
+# 1. Nodes Ready, etcd quorum, storage reachable.
+./infra/devcontainer/dev.sh run bash -c 'kubectl --context k3s-prod get nodes'
+./infra/devcontainer/dev.sh run bash -c 'kubectl --context k3s-prod get --raw=/healthz/etcd'
+
+# 2. Resume: un-hibernate Postgres, then resume Flux.
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh resume'
+```
+
+**Un-hibernating Postgres is the step everyone forgets.** The annotation is imperative and survives
+a Flux resume, so resuming Flux alone leaves all three databases down and Keycloak, Nextcloud and
+Semaphore looking broken for reasons that point nowhere near Postgres. `resume` does it first, for
+exactly that reason.
+
+Flux restores every scaled-down replica count **and** the VM's `running: true` from git, so nothing
+needs undoing by hand.
+
+### What "still broken" looks like when it is actually fine
+
+* **`4/19` Kustomizations Ready for several minutes.** The dependency graph serialises behind
+  `platform-config`; 15 of them report `dependency ... is not ready` until it finishes. Check
+  `platform-config` itself is `Ready=True` and its `lastAppliedRevision` matches the GitRepository
+  artifact — if it is, wait.
+* **One or more Longhorn volumes `degraded`.** Any volume that was still attached at poweroff
+  rebuilds its lagging replica automatically. On 2026-10-17 it was Prometheus's 50Gi TSDB; it went
+  healthy on its own. Worry only if it is still degraded after ~30 minutes.
+* **`keycloak-operator` crashlooping, then recovering.** It is the CRD reconciler, not in the
+  request path; Keycloak's StatefulSet stays 2/2 and auth never goes down. See
+  `/runbooks/keycloak-*` and the known OOM-at-450Mi behaviour.
+
+### What is actually broken and needs you
+
+* **An `oauth2-proxy` replica stuck in CrashLoopBackOff.** It performs OIDC discovery at startup and
+  **exits 1** on the `503 no healthy upstream` it gets while Keycloak is still coming up, then sits
+  in exponential backoff long after Keycloak is fine. It has no startup dependency on Keycloak.
+  Delete the pod once and it comes up clean:
+
+  ```bash
+  ./infra/devcontainer/dev.sh run bash -c \
+    'kubectl --context k3s-prod -n oauth2-proxy delete pod <name>'
+  ```
+
+* **Orphaned `Unknown`/`Error` Job pods** from CronJobs that were mid-run at poweroff. They never
+  recover; delete them.
+
+## Verifying you are actually back
+
+```bash
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh status'
+# nodes 3 Ready | flux 19/19 | longhorn 0 not healthy | postgres 9 pods | unifi 1 VMI
+
+# DNS, through PiHole's VIP
+./infra/devcontainer/dev.sh run bash -c 'nslookup home.keithjackson.dev 192.168.2.23'
+
+# The Gateway actually serving (401 on an auth-gated host is CORRECT)
+for h in home.keithjackson.dev gitea.home.keithjackson.dev plex.home.keithjackson.dev; do
+  curl -s -o /dev/null -w "$h %{http_code}\n" -k --resolve $h:443:192.168.2.20 https://$h/
+done
+```
+
+Expect `200`, `200`, `401`.
@@ -52,6 +52,13 @@ configMapGenerator:
      - backup-failure=backup-failure.md
      - backup-missed=backup-missed.md
      - backup-partial=backup-partial.md
+      # Operator procedure, not an alert page — nothing links here from an alert. Served because
+      # the whole-cluster shutdown had NO written procedure until 2026-10-17 (infra/cluster.sh is
+      # virsh-based and only ever applied to the decommissioned dev cluster), so the UPS move was
+      # improvised live, and the one hazard it exposed -- a StatefulSet with
+      # persistentVolumeClaimRetentionPolicy whenScaled: Delete loses its PVC when scaled to 0 --
+      # destroyed monitoring/loki's volume before anyone noticed.
+      - cluster-maintenance-shutdown=cluster-maintenance-shutdown.md
      - cdi-import-stuck=cdi-import-stuck.md
      - cert-expiry=cert-expiry.md
      - cert-issuance=cert-issuance.md
Author	SHA1	Message	Date
jakman85andClaude Opus 5	713b0c3dba	fix(renovate): the config was INVALID, so the first manual run errored out gate / gate (pull_request) Successful in 1m55s Details gate / conformance (pull_request) Has been skipped Details The operator ran the Renovate workflow manually and it failed. The cause is not the workflow: renovate.json was never a valid Renovate config. It carried five pseudo-comment keys (_comment, _kubernetes_comment, _unmanageable_comment, _ignorePaths_comment, _docker_comment) because JSON has no comments, and Renovate REJECTS unknown top-level options. Proven with the official validator: ERROR: Found errors in configuration Invalid configuration option: _comment Invalid configuration option: _docker_comment Invalid configuration option: _ignorePaths_comment Invalid configuration option: _kubernetes_comment Invalid configuration option: _unmanageable_comment This is the SECOND independent reason Renovate never worked, on top of PR #77's cron firing outside renovate.json's own schedule window. Either alone was enough to produce "nothing ever happens"; #73 shipped both. Converted renovate.json -> renovate.json5. JSON5 permits real // comments and Renovate discovers renovate.json5 natively; nothing in .gitea/ or ci/ pins the old filename and no RENOVATE_CONFIG_FILE is set. Every word of the original rationale is preserved as positioned comments (74 comment lines) rather than flattened into a description string. Verified the conversion dropped nothing: 18 non-comment keys before and after, no missing/extra keys, no changed values, docker: {enabled: true} still present. The validator now returns "Config validated successfully". DISPROVED while here: `enabledManagers` containing bare `regex` was suspected of needing to be `custom.regex` (which would silently disable every inline `# renovate:` marker). The validator accepts `regex`; unfounded, unchanged. Renovate has still never completed a run -- this fixes one of two blockers and nothing in the gate catches an invalid config. See the handoff. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 03:10:25 -05:00
jakman85	c340bbfc4b	Merge pull request 'fix(conformance): one regex made the merge gate take 28 minutes instead of 2' (#76 ) from fix/ha-check-catastrophic-regex into main gate / gate (push) Successful in 1m56s Details gate / conformance (push) Has been skipped Details Reviewed-on: #76 Reviewed-by: Keith Jackson <[email protected]>	2026-10-18 07:51:51 +00:00
jakman85	a9a529750d	Merge pull request 'fix(unattended-upgrades): Debian has no reboot-sentinel package, so ship the writer' (#75 ) from fix/unattended-upgrades-debian-sentinel into main gate / conformance (push) Has been cancelled Details gate / gate (push) Has been cancelled Details Reviewed-on: #75	2026-10-18 07:40:20 +00:00
jakman85andClaude Opus 5	793c3940a8	fix(conformance): one regex made the merge gate take 28 minutes instead of 2 gate / gate (pull_request) Successful in 1m55s Details gate / conformance (pull_request) Has been skipped Details ha-control-plane-as-code/check.sh had: re.search(r"--server https://.?\n(?:.\n){0,10}?\swhen:...'secondary'", K3S_TEXT, re.S) With re.S every `.` matches newlines, so `.?` and the nested `(?:.\n){0,10}?` can each consume the whole document -- nested unbounded repetition, which backtracks exponentially on a failed or late match. MEASURED in CI via `docker top` on the live job container: python3 at 19:54 of CPU time, which is essentially the entire ~28 minute gate. Localised to the exact line by extracting the inline python and running it under faulthandler.dump_traceback_later, which named re/__init__.py:177 in search from this call -- not inferred from reading. Replaced `.` with `[^\n]` and dropped re.S, so the {0,10} is a real ten-line window with nothing to backtrack into. On the real input (22,179 chars): 0.2 ms, match still found. Whole check: 0.199s, rc 0, 115 assertions, identical success message. WHY IT SURFACED NOW, AND IT WAS MINE: K3S_TEXT is every .yml in roles/k3s_server concatenated. The regex was latent for as long as it existed; PR #71 added ~100 lines to that role (kubelet graceful-shutdown config), growing the input past the point where exponential backtracking stopped being survivable. WHY ONLY infra/* WAS SLOW: touched-requirements.sh maps infra/* to R-ENV-01, so the L0 run becomes --include-scope whole-repo --requirements R-ENV-01, which selects this whole-repo check. Doc/platform changes never did -- #69 1m55s and #72 1m53s stayed fast while #71 27m44s, the #73 merge 27m46s and #75 all ran ~28m. The pattern is unique in the repo (grep over all l0-static check.sh files). Not re-timed in CI post-fix; this PR's own run is the first datapoint. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 02:38:23 -05:00
jakman85andClaude Opus 5	ef8ef5ac29	fix(unattended-upgrades): Debian has no reboot-sentinel package, so ship the writer gate / gate (pull_request) Successful in 27m51s Details gate / conformance (pull_request) Has been skipped Details The first real run failed on all three nodes: fatal: [k3s-prod-1]: "No package matching 'update-notifier-common' is available" update-notifier-common is an UBUNTU package and does not exist in Debian -- `apt-cache policy` returns Candidate: (none) on trixie. The role asserted it "owns the hook that creates /var/run/reboot-required", which is true on Ubuntu and false here, so the role could never have worked. Three further measurements settled the replacement: notify-reboot-required is absent; NO linux-image-* postinst references it (invoking it is an Ubuntu patch, so dropping a script at that path would never be called); and no hook under apt.conf.d or /etc/kernel mentions reboot-required. Debian trixie ships no mechanism at all. So the role now provides it: * /usr/local/sbin/k3s-notify-reboot-required -- touches the sentinel when the running kernel is not the newest installed, using `linux-version` (from linux-base, a dependency of every linux-image, measured present) because kernel version ordering is not string ordering. * /etc/apt/apt.conf.d/99-k3s-reboot-required -- DPkg::Post-Invoke, `\|\| true` so it can never abort an apt transaction. /run is tmpfs (measured), so the sentinel self-clears on boot; no cleanup task. The verify assert was ALSO weaker than it looked: a `find` glob for update-notifier / unattended-upgrades under apt.conf.d would have matched Debian's own unattended-upgrades conffile and reported "writer present" while none existed. It now stats the two exact paths this role owns and requires the script to be executable. Newly verified: the script ran on prod-1 as unprivileged k3s under sh -x -- running=newest=7.1.8+deb13-amd64, took the equal branch, exited 0, wrote nothing. Correct. sh -n and bash -n clean. Still unverified: the WRITING half never executes while running == newest, so the sentinel has not been seen created and kured has not been seen react. The honest test is the next kernel upgrade. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 01:43:43 -05:00
jakman85	ee196c7bcd	Merge pull request 'feat(upgrades): automate node reboots (kured) and wire Renovate, which had never run' (#73 ) from feat/automated-upgrades into main gate / gate (push) Successful in 27m46s Details gate / conformance (push) Has been skipped Details Reviewed-on: #73 Reviewed-by: Keith Jackson <[email protected]>	2026-10-18 06:28:30 +00:00
jakman85	83d3568150	Merge pull request 'feat(shutdown): configure graceful node shutdown, and never scale a Delete-policy StatefulSet' (#71 ) from feat/graceful-cluster-shutdown into main gate / gate (push) Successful in 27m39s Details gate / conformance (push) Has been skipped Details Reviewed-on: #71	2026-10-18 05:51:20 +00:00
jakman85	24bea918ab	Merge pull request 'fix(coredns): hold in-cluster DNS at 2 replicas via an HPA, because k3s owns the Deployment' (#74 ) from fix/coredns-ha into main gate / conformance (push) Has been cancelled Details gate / gate (push) Has been cancelled Details Reviewed-on: #74	2026-10-18 05:50:46 +00:00
jakman85andClaude Opus 5	5642881c4d	fix(coredns): hold in-cluster DNS at 2 replicas via an HPA, because k3s owns the Deployment gate / gate (pull_request) Successful in 1m52s Details gate / conformance (pull_request) Has been skipped Details MEASURED on prod 2026-10-18: kube-system/coredns had replicas: 1. In-cluster DNS was a single pod on a single node, so draining or rebooting that node was a CLUSTER-WIDE in-cluster DNS outage until the pod rescheduled -- every Service lookup, every CNPG replica finding its primary, every operator addressing the API by name. It was invisible because 1/1 Ready looks healthy. It is urgent rather than latent now: the scheduled reboot automation on feat/automated-upgrades drains and reboots one node at a time, unattended, overnight -- turning a single point of failure into a recurring one. WHY AN HPA AND NOT replicas: 2 -- the whole decision. k3s OWNS the coredns Deployment: AddOn/coredns, source /data/k3s/server/manifests/coredns.yaml, managedFields managers deploy@k3s-prod-1 + k3s, objectset.rio.cattle.io/hash label. k3s re-stages its bundled manifests on startup, so replicas: 2 written there -- or a kubectl scale -- is reverted on the next restart or upgrade. Rejected alternatives: * coredns.yaml.skip + our own templated copy (the roles/kube_vip pattern). Deterministic, but takes ownership of coredns from k3s permanently so k3s upgrades stop updating it. Too high a price for a replica count. * A Flux patch of the Deployment. Rejected outright: Flux and k3s's deploy controller would both own one object and fight -- the default-deny NetworkPolicy drift-loop shape (~2500 events/10min) this cluster already hit. An HPA is a separate object k3s does not own, driving /scale rather than the Deployment spec, so there is no shared-ownership fight; if k3s re-stages replicas: 1 it is re-asserted within a reconcile. Disclosed cost: a brief window at 1 replica after a k3s restart. It is a FLOOR-HOLDER, not an autoscaler -- the CPU metric exists only so the autoscaling/v2 object is valid. Measured: 5m/4m against a 100m request (~5%), so the 80% target is never approached. scaleDown stabilization 600s because DNS is the worst thing to flap; scaleUp immediate, since that restores redundancy. The kustomization edit is ADDITIVE: platform/coredns/ already existed and holds the coredns-custom split-horizon ConfigMap (R-DNS-01/03), which is untouched. UNAPPLIED. The HPA has never run, and the claim that k3s reverts replicas on restart is reasoned, not observed. After merge check `describe hpa coredns` for ScalingActive=True -- an inert HPA looks identical to a working one because the hand scale already left 2 replicas. See the handoff entry. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 00:44:09 -05:00
jakman85	4d489f2059	Merge pull request 'feat(keycloak): add passkey (WebAuthn passwordless) login, additive and optional' (#72 ) from feat/keycloak-passkeys into main gate / gate (push) Successful in 1m53s Details gate / conformance (push) Has been skipped Details Reviewed-on: #72	2026-10-18 05:44:03 +00:00
jakman85andClaude Opus 5	16894b7b73	feat(keycloak): declare passkey (WebAuthn passwordless) login for the homelab realm gate / gate (pull_request) Successful in 1m53s Details gate / conformance (pull_request) Has been skipped Details Adds the realm's WebAuthn Passwordless policy and restructures the browser-mfa flow so a passkey is an ALTERNATIVE beside the password form. Additive and optional by design: this IdP gates every SSO app plus kubectl, so a mandatory passkey flow that misfires is a total lock-out. Enrolment is not forced. Policy: RP ID is ${BASE_DOMAIN} (not the keycloak host) because a passkey's RP ID is fixed at enrolment and must not be bound to a name that can move; resident key required (a non-discoverable credential is a second factor, not a passkey); user verification required (without it, possession alone is a complete login). Flow: auth-username-password-form is split into auth-username-form + auth-password-form, because the server must know who is logging in before it can decide whether a passkey exists. Conditional OTP for platform-admins is relocated intact onto the password branch only — a UV-required passkey is already two phishing-resistant factors. No requiredActions block is declared, deliberately: Keycloak 26.0.6 treats requiredActions as REPLACE not merge, so declaring one would delete the default set including CONFIGURE_TOTP and lock every platform-admin out of the OTP step this flow still enforces. webauthn-register-passwordless is already registered enabled-but-not-default by Keycloak's own defaults. UNAPPLIED: the realm import is a one-shot resting at Done=True/Started=False, so this reaches the live realm never. See the handoff entry and the README section. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-17 23:23:36 -05:00
jakman85andClaude Opus 5	2f2e98aa19	feat(shutdown): configure graceful node shutdown, and never scale a Delete-policy StatefulSet gate / gate (pull_request) Successful in 27m44s Details gate / conformance (pull_request) Has been skipped Details All three nodes had to be powered off to move them onto a UPS, and there was NO procedure: infra/cluster.sh stop is virsh-based and only ever applied to the decommissioned dev cluster. The sequence was improvised live. Two defects came out of doing it. 1. GRACEFUL NODE SHUTDOWN WAS UNCONFIGURED ON EVERY PROD NODE. No shutdownGracePeriod anywhere in infra/ansible/, so `shutdown -h` stopped k3s, containerd went with it, and every pod was SIGKILLed where it stood -- 9 CNPG instances mid-checkpoint, the UniFi VM, 25 attached Longhorn volumes. roles/k3s_server now sets kubelet-arg shutdown-grace-period=90s and shutdown-grace-period-critical-pods=20s. The half that silently defeats the other half: this is enforced by LOGIND, not the kubelet. The kubelet holds an inhibitor DELAY lock and systemd waits at most InhibitDelayMaxSec -- DEFAULT 5 SECONDS -- then proceeds regardless, truncating the drain with no error. The role ships a logind.conf.d drop-in (120) and ASSERTS cap >= grace period, because the failure is invisible. 2. SCALING A StatefulSet TO 0 DELETED ITS PVC AND VOLUME. monitoring/loki carries persistentVolumeClaimRetentionPolicy whenScaled: Delete, so the quiesce destroyed storage-loki-0 outright. Loki stores type: filesystem, so that PVC was the only copy; 72h retention bounded the loss, the mechanism does not. Symptom was the volume count going 25 -> 24, first misread as a miscount. Repaired: scale back to the declared 1 recreated the PVC and loki-0 is 2/2 Running. New infra/maintenance/quiesce.sh (quiesce\|resume\|status) encodes the sequence that worked and REFUSES to scale any whenScaled: Delete StatefulSet -- it stays running, its volume hard-detaches, and it rebuilds on restart. A rebuild beats a deletion. Discovery is computed from the live cluster, so a newly onboarded service needs no edit here. runbooks/cluster-maintenance-shutdown.md is the operator page: order in both directions, TrueNAS-after-nodes (hard NFS mount wedges kubelet), the un-hibernate-Postgres step Flux will NOT do for you, and a "looks broken but is fine" section separating the 4/19 Flux cascade, the degraded-and-rebuilding volume and the self-recovering keycloak-operator from the one thing that needs a human (a stuck oauth2-proxy replica). THE KUBELET CHANGE HAS NEVER BEEN APPLIED OR TESTED -- it needs a rolling k3s restart, which is an operator action. Review config.yaml's kubelet-arg before applying: a bad config.yaml is how k3s fails to come up. See the handoff entry. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-17 22:26:47 -05:00