feat(repo)!: restructure around the dsh-harness image and one example per implementation

- the root Dockerfile is the primary artifact; versions.env is the single source of truth
- merge gateway-api/dsh-demo into examples/dsh-agents-as-a-service (manifests/, exposure variants)
- move the single-tenant template into examples/minimal-single-tenant
- publish the gateway as a nested package under the repository image
- mirror the DSH ref for release identities (first release dsh-v0.2.1-rc.2-r2)
- CI: lint/python/manifests/gateway-image, reusable multi-arch build, tag-driven release, weekly e2e
- docs: README, docs/{main-image,examples,gitflow,versioning}, example READMEs, AGENTS.md, governance
- SSO is opt-in again; gateway pull policy and cookie defaults match the documented demo

BREAKING CHANGE: example manifest paths, the gateway image name, and the removal
of deploy/ and gateway-api/ affect existing deployments; see the migration table
in README.md.

examples/dsh-agents-as-a-service/manifests/exposure/gateway-api-sso/70-gateway.yaml

@@ -0,0 +1,25 @@
+# Browser entry point (TLS) for the gateway-api-sso variant: terminates TLS
+# for dsh-demo.example.com and routes through 71-httproute.yaml to
+# oauth2-proxy, which authenticates the browser before the gateway.
+# Mutually exclusive with ../../ingress/ (see ../../README.md). The
+# "dsh-demo-tls" Secret comes from 74-tls-secret.yaml.example.
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: dsh-gateway
+  namespace: dsh-demo
+  labels:
+    app.kubernetes.io/part-of: dsh-demo
+spec:
+  gatewayClassName: traefik
+  listeners:
+    - name: https
+      port: 8443
+      protocol: HTTPS
+      tls:
+        mode: Terminate
+        certificateRefs:
+          - name: dsh-demo-tls
+      allowedRoutes:
+        namespaces:
+          from: Same

examples/dsh-agents-as-a-service/manifests/exposure/gateway-api-sso/71-httproute.yaml

@@ -0,0 +1,23 @@
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: dsh-gateway
+  namespace: dsh-demo
+  labels:
+    app.kubernetes.io/part-of: dsh-demo
+spec:
+  parentRefs:
+    - name: dsh-gateway
+      namespace: dsh-demo
+      sectionName: https
+  hostnames:
+    # TODO: replace with the actual public FQDN before applying.
+    - dsh-demo.example.com
+  rules:
+    - backendRefs:
+        # Route through oauth2-proxy (GitHub OAuth) first; it authenticates the
+        # browser and forwards to dsh-gateway:8080 with X-Forwarded-User set.
+        # The gateway only trusts that header when AUTH_PROXY_HEADER is set on
+        # its Deployment — see 72-oauth2-proxy.yaml and ../README.md.
+        - name: oauth2-proxy
+          port: 4180

examples/dsh-agents-as-a-service/manifests/exposure/gateway-api-sso/72-oauth2-proxy.yaml

@@ -0,0 +1,134 @@
+# oauth2-proxy — GitHub OAuth login in front of the dsh-gateway.
+#
+# Runs as a reverse proxy: it authenticates the browser against GitHub
+# (restricted to a configured organization), then forwards the request to
+# the dsh-gateway Service with the authenticated identity in X-Forwarded-User
+# (plus X-Auth-Request-* via --set-xauthrequest). The gateway trusts that
+# header only when AUTH_PROXY_HEADER is set on its Deployment.
+#
+# ENABLING SSO TAKES BOTH SIDES (see ../../../exposure/README.md):
+#   1. Set AUTH_PROXY_HEADER=X-Forwarded-User on deploy/dsh-gateway, otherwise
+#      the gateway ignores the header and the login is cosmetic:
+#        kubectl -n dsh-demo set env deploy/dsh-gateway \
+#          AUTH_PROXY_HEADER=X-Forwarded-User COOKIE_SECURE=true
+#   2. Make dsh-gateway reachable ONLY through this proxy: keep the Service
+#      ClusterIP, route browser traffic through 71-httproute.yaml, and do not
+#      apply ../ingress/ (or anything else that reaches the gateway). A
+#      client that can reach dsh-gateway:8080 can spoof X-Forwarded-User and
+#      impersonate any user.
+# TLS terminates at the Gateway listener (70-gateway.yaml); keep
+# --cookie-secure=true and COOKIE_SECURE=true on the gateway.
+#
+# The image is pinned to quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
+# (versions.env: OAUTH2_PROXY_IMAGE). Credentials come from the
+# "oauth2-proxy" Secret (see 73-oauth2-proxy-secret.yaml.example); this
+# manifest never carries secrets.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: oauth2-proxy
+  namespace: dsh-demo
+  labels:
+    app: oauth2-proxy
+    app.kubernetes.io/part-of: dsh-demo
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: oauth2-proxy
+  template:
+    metadata:
+      labels:
+        app: oauth2-proxy
+        app.kubernetes.io/part-of: dsh-demo
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 2000
+        runAsGroup: 2000
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: oauth2-proxy
+          image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
+          imagePullPolicy: IfNotPresent
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          args:
+            - --http-address=0.0.0.0:4180
+            - --provider=github
+            # TODO: replace with the GitHub organization allowed to sign in.
+            - --github-org=your-github-org
+            - --email-domain=*
+            # Reverse-proxy target: the gateway backend Service.
+            - --upstream=http://dsh-gateway:8080
+            # Public callback (TLS terminates at the Gateway listener).
+            # TODO: replace with the actual public FQDN.
+            - --redirect-url=https://dsh-demo.example.com/oauth2/callback
+            - --cookie-secure=true
+            - --cookie-name=_oauth2_proxy
+            # Also expose X-Auth-Request-User/Email/Groups upstream.
+            - --set-xauthrequest
+            # Single provider: skip the provider-selection page.
+            - --skip-provider-button
+          env:
+            - name: OAUTH2_PROXY_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: oauth2-proxy
+                  key: client-id
+            - name: OAUTH2_PROXY_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: oauth2-proxy
+                  key: client-secret
+            - name: OAUTH2_PROXY_COOKIE_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: oauth2-proxy
+                  key: cookie-secret
+          ports:
+            - name: http
+              containerPort: 4180
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 1
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 3
+          resources:
+            requests:
+              cpu: 10m
+              memory: 32Mi
+            limits:
+              cpu: 200m
+              memory: 128Mi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: oauth2-proxy
+  namespace: dsh-demo
+  labels:
+    app: oauth2-proxy
+    app.kubernetes.io/part-of: dsh-demo
+spec:
+  selector:
+    app: oauth2-proxy
+  ports:
+    - name: http
+      port: 4180
+      targetPort: http

examples/dsh-agents-as-a-service/manifests/exposure/gateway-api-sso/73-oauth2-proxy-secret.yaml.example

@@ -0,0 +1,39 @@
+# EXAMPLE ONLY — do not apply as-is.
+#
+# oauth2-proxy reads its GitHub OAuth credentials and cookie-signing secret from
+# this Secret. Populate real values and apply:
+#
+#   kubectl -n dsh-demo create secret generic oauth2-proxy \
+#     --from-literal=client-id='<GitHub OAuth App client ID>' \
+#     --from-literal=client-secret='<GitHub OAuth App client secret>' \
+#     --from-literal=cookie-secret="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
+#
+# The cookie secret must decode (base64) to exactly 16, 24, or 32 bytes.
+# oauth2-proxy base64-decodes it, so it must be URL-safe, unpadded base64.
+# Generate it with either of:
+#
+#   python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
+#   openssl rand -base64 32 | tr -- '+/' '-_' | tr -d '='
+#
+# Do NOT use plain `openssl rand -base64 32`: that yields 44 characters of
+# standard base64 (with "=" and possibly "+"/"/"), which oauth2-proxy cannot
+# decode and therefore treats as 44 raw bytes, failing with "cookie_secret must
+# be 16, 24, or 32 bytes ... but is 44 bytes".
+#
+# GitHub OAuth App (https://github.com/settings/developers):
+#   Homepage URL            https://dsh-demo.example.com
+#   Authorization callback  https://dsh-demo.example.com/oauth2/callback
+#   (replace dsh-demo.example.com with the actual public FQDN)
+#
+# NOTE: pass the base64 value as-is via --from-literal (kubectl stores the
+# literal; it does not base64-encode it a second time).
+apiVersion: v1
+kind: Secret
+metadata:
+  name: oauth2-proxy
+  namespace: dsh-demo
+type: Opaque
+stringData:
+  client-id: "<github-oauth-app-client-id>"
+  client-secret: "<github-oauth-app-client-secret>"
+  cookie-secret: "<urlsafe-unpadded-base64-of-32-random-bytes>"

examples/dsh-agents-as-a-service/manifests/exposure/gateway-api-sso/74-tls-secret.yaml.example

@@ -0,0 +1,17 @@
+# EXAMPLE ONLY — do not apply as-is.
+#
+# Copy to tls-secret.yaml and populate with real base64-encoded PEM material,
+# then apply. The secret must live in the dsh-demo namespace and be named
+# "dsh-demo-tls" (referenced by 70-gateway.yaml).
+#
+#   kubectl -n dsh-demo create secret tls dsh-demo-tls \
+#     --cert=tls.crt --key=tls.key --dry-run=client -o yaml > tls-secret.yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: dsh-demo-tls
+  namespace: dsh-demo
+type: kubernetes.io/tls
+data:
+  tls.crt: <base64-encoded-certificate>
+  tls.key: <base64-encoded-private-key>