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.

.github/workflows/e2e-kind.yaml

@@ -0,0 +1,78 @@
+# Weekly end-to-end run of the agents-as-a-service example against a real kind
+# cluster with agent-sandbox installed. Scheduled (not PR-blocking) so upstream
+# controller churn does not block merges; also available on demand.
+name: E2E (kind)
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: e2e-kind
+  cancel-in-progress: false
+
+jobs:
+  e2e:
+    name: Example walkthrough on kind
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Create kind cluster
+        uses: helm/kind-action@1544676c07bb3570fcb70166beaa07c4528fd4aa # v1.15.1
+        with:
+          version: v0.33.0
+          cluster_name: dsh-e2e
+      - name: Read versions.env
+        run: |
+          set -euo pipefail
+          while IFS= read -r line; do
+            case "$line" in ''|'#'*) continue ;; esac
+            echo "$line" >> "$GITHUB_ENV"
+          done < versions.env
+      - name: Install agent-sandbox
+        run: |
+          set -euo pipefail
+          kubectl apply -f "https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$AGENT_SANDBOX_VERSION/sandbox-with-extensions.yaml"
+          kubectl -n agent-sandbox-system rollout status deployment --timeout=180s
+          kubectl wait --for=condition=Established crd/sandboxtemplates.extensions.agents.x-k8s.io --timeout=180s
+          kubectl wait --for=condition=Established crd/sandboxwarmpools.extensions.agents.x-k8s.io --timeout=180s
+          kubectl wait --for=condition=Established crd/sandboxclaims.extensions.agents.x-k8s.io --timeout=180s
+          kubectl wait --for=condition=Established crd/sandboxes.agents.x-k8s.io --timeout=180s
+      - name: Set up Python (WebSocket checks)
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Install WebSocket client
+        run: pip install "websockets==17.3"
+      - name: Run the example walkthrough
+        env:
+          KIND_CLUSTER: dsh-e2e
+        run: examples/dsh-agents-as-a-service/scripts/e2e-kind.sh
+      - name: Collect cluster state
+        if: always()
+        run: |
+          set -euo pipefail
+          {
+            echo "== resources =="
+            kubectl get all,pvc -n dsh-demo -o wide 2>&1 || true
+            echo "== events =="
+            kubectl get events -n dsh-demo --sort-by=.lastTimestamp 2>&1 || true
+            echo "== gateway logs =="
+            kubectl -n dsh-demo logs deploy/dsh-gateway --tail=200 2>&1 || true
+          } > /tmp/e2e-cluster.txt
+      - name: Upload cluster state
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: e2e-cluster-state
+          path: /tmp/e2e-cluster.txt
+          if-no-files-found: warn
+          retention-days: 7