feat(bulwark): Gateway-API as an alternative to the Ingress

Group 3 of the #114 sweep. One route, one rule, at the root - and THREE
EXPECTATIONS ABOUT THIS CHART DID NOT SURVIVE CONTACT WITH IT:

  - #114 says bulwark has TWO Ingress objects. It has ONE. keycloak has two.
  - #114's measured table lists bulwark under rewrite-target. It has no
    rewrite-target annotation and CANNOT have one: NEXT_PUBLIC_BASE_PATH is
    compiled into the bundle, so the application cannot be served under a
    sub-path, and stripping a prefix at the proxy would yield a page that
    loads and then fetches everything from the wrong place. Every occurrence
    of the string "rewrite-target" in this chart - values.yaml, the schema,
    the Ingress template - is an explanation of exactly that. A grep for the
    string finds the refutations and counts them as occurrences.
  - ci/run-httproute-match-test.sh said in its header that bulwark was the
    second rewrite-target chart and would meet the #118 prefix/redirect
    assurance when group 3 landed. Group 3 landed and it does not: with no
    URLRewrite on a prefix other than "/", the assurance's precondition is
    never met here. The header is corrected rather than left standing, and it
    now says freesailarr is the only chart the pairing applies to.

So no redirect rule is added, and none is needed.

WHAT THIS MODE DROPS, MEASURED ON THE LIVE OBJECT rather than inferred. On
2026-10-12 the live Ingress on webmail.bekemeyer-klein.de carried

    nginx.ingress.kubernetes.io/proxy-body-size: 25m

supplied by the OPERATOR through ingress.annotations - values.yaml recommends
exactly that value and explains why the chart cannot pick it, so the chart
sets nothing and a reader of this repository alone would not find it. It is
the single annotation this installation depends on, and the Gateway API has no
body-size counterpart: implementation policy, not routing. Per decisions 1 and
2 of #114 it is NAMED, not rebuilt - in values.yaml, in the schema and in the
Gateway branch of NOTES.txt, in this application's own terms: an attachment
above the Gateway's default is rejected before Bulwark sees a byte, the 413
comes from the proxy, and it arrives after the user has written the mail and
attached the file.

CORRECTED CLAIM, the same one garage and calibre-web-automated needed: the
Ingress template, the bulwark.publicUrl helper and the schema all stated that
nothing outside the Ingress template FUNCTIONALLY reads ingress.domain. The
HTTPRoute reads it, so the claim held only while both modes were off. All
three now say so, and the route carries a required() of its own.

bulwark.publicUrl follows the ACTIVE mode instead of always printing
ingress.domain. The two differ exactly when httpRoute.hostnames is set, which
is how a migration off the Ingress runs - and printing the old host there
would hand the operator an OIDC redirect URI for the hostname being migrated
away from, a failure that surfaces as a rejected login at the identity
provider and says nothing about this chart.

Minor: additive, defaults unchanged. Empty helm template diff against
origin/main with ci/bulwark/test-values.yaml.

Part of #114

bulwark/values.yaml

@@ -711,6 +711,11 @@ ingress:
   # away would produce a release that renders cleanly and whose operator is told
   # to register `https:///auth/callback`.
   #
+  # AND A THIRD TIME SINCE Gitea #114: the HTTPRoute reads it as its hostname
+  # when httpRoute.hostnames is empty, with a required() of its own. So this
+  # value is mandatory in GATEWAY mode as well, and only a release with both
+  # modes off can do without it.
+  #
   # BULWARK IS SERVED AT THE ROOT OF THIS HOST AND CANNOT BE SERVED UNDER A
   # PATH. NEXT_PUBLIC_BASE_PATH is compiled into the bundle (point 4 at the top
   # of this file), so a sub-path deployment would need a rebuilt image. The
@@ -734,4 +739,80 @@ ingress:
   # (or whatever the mail server accepts) to match stalwart's own limit. The
   # chart does not set it, because the right number is the mail server's and
   # this chart does not know it.
+  #
+  # AND THAT RECOMMENDATION IS NOT HYPOTHETICAL - IT IS WHAT THIS INSTALLATION
+  # RUNS ON. Measured on 2026-10-12: the live Ingress on
+  # webmail.bekemeyer-klein.de carries exactly
+  # nginx.ingress.kubernetes.io/proxy-body-size: 25m, supplied here by the
+  # operator. In GATEWAY MODE this whole block is INERT - the Gateway API has
+  # no annotation channel for controller behaviour, and body size has no
+  # counterpart in the specification at all. Read the httpRoute block below
+  # before switching modes.
   annotations: {}
+
+# THE GATEWAY-API ALTERNATIVE TO THE INGRESS (Gitea #114).
+#
+# Mutually exclusive with ingress.enabled - the render aborts when both are
+# true, and the message names both value paths. The chart renders ONLY an
+# HTTPRoute with parentRefs: no Gateway, no class, no Certificate, and no
+# implementation-specific policy object. Class and certificate sit on the
+# Gateway and its listeners and belong to the platform (cluster-config), which
+# is what keeps the Gateway implementation replaceable without touching this
+# chart again.
+#
+# ONE ROUTE, ONE RULE, AT THE ROOT. "/" is as permanent here as it is on the
+# Ingress, for the same reason: NEXT_PUBLIC_BASE_PATH is compiled into the
+# bundle, so Bulwark cannot be served under a sub-path and there is nothing for
+# a URLRewrite filter to strip. This chart renders no such filter and needs
+# none - which also means the #118 prefix/redirect assurance in
+# ci/run-httproute-match-test.sh has no precondition to meet here.
+#
+# WHAT THIS MODE COSTS, AND IT IS THE ONE ANNOTATION THIS INSTALLATION USES.
+# proxy-body-size: 25m is set on the live Ingress by the operator (see the
+# annotations block above). It is GONE in this mode and cannot be rebuilt here:
+# the Gateway API knows no body size, that is implementation policy, and
+# decision 2 of #114 says the limit is documented rather than reconstructed
+# with a policy object that would bind this chart to one implementation.
+#
+# What that looks like in practice, for THIS application: an attachment above
+# the GATEWAY's default is rejected before Bulwark sees a byte, and the 413
+# comes from the proxy. The user is composing mail with a file attached, so the
+# failure arrives at the least recoverable moment and reads like a webmail
+# fault. Set the equivalent next to the Gateway - in that implementation's own
+# object - BEFORE pointing DNS at it, and size it to what the MAIL SERVER
+# accepts (stalwart), not to what feels generous. NOTES.txt prints this in
+# Gateway mode.
+#
+# THE GATEWAY-API CRDs MUST BE PRESENT. The chart cannot detect them
+# (.Capabilities.APIVersions is unreliable at template time) and an HTTPRoute
+# without them fails at install, so this is a value and not a guess.
+httpRoute:
+  enabled: false
+
+  # The Gateway(s) the route attaches to - a platform object, usually in
+  # another namespace, whose listener must allow this namespace in
+  # allowedRoutes. Entries are the Gateway API's ParentReference (name, and
+  # optionally namespace, sectionName, port, group, kind), passed through
+  # unchanged:
+  #
+  #   parentRefs:
+  #     - name: public
+  #       namespace: gateway
+  #       sectionName: https
+  #
+  # REQUIRED while httpRoute.enabled is true - the render aborts on an empty
+  # list, because a route without a parent is created, is valid and routes
+  # nothing, with no event to say so.
+  parentRefs: []
+
+  # Empty means [ingress.domain], so the hostname has one source of truth. Set
+  # explicitly only to publish under a different or an additional name - which
+  # is how a migration from the Ingress runs: the HTTPRoute takes a second
+  # hostname while the Ingress keeps ingress.domain.
+  #
+  # AND IF YOU SET IT, REGISTER THAT ORIGIN WITH THE IDENTITY PROVIDER FIRST.
+  # NOTES.txt derives the OIDC redirect URI from the ACTIVE mode's hostname, so
+  # a second hostname means a second redirect URI - a login that returns to an
+  # unregistered origin is rejected at the provider, which says nothing about
+  # this chart.
+  hostnames: []