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.

build.sh

@@ -1,68 +1,19 @@
 #!/usr/bin/env bash
-# Build the DSH Web and/or gateway images locally.
+# Deprecated compatibility shim: "make" is the canonical entrypoint.
 #
-# Usage:
-#   ./build.sh              # build the DSH Web image, then run it interactively
-#   ./build.sh web          # build the DSH Web image only
-#   ./build.sh gateway      # build the gateway image (examples/.../gateway/)
+#   ./build.sh            -> make run   (build the main image, then run it)
+#   ./build.sh web        -> make image
+#   ./build.sh gateway    -> make gateway
 #
-# Overridable environment:
-#   DSH_VERSION    DSH git ref to build    (default dsh-v0.2.1-rc.2)
-#   PNPM_VERSION   pnpm version            (default 11.28.5)
-#   IMAGE          DSH Web image tag       (default dsh-web:<version>)
-#   DSH_PORT       host port for docker run (default 3080)
-#   GATEWAY_IMAGE  gateway image tag       (default ghcr.io/...:gateway)
-#   RUN            0 to build without running (default 1)
+# Use the Makefile targets directly for everything else (test, lint, check, e2e).
 set -euo pipefail
 cd "$(dirname "$0")"
 
-DSH_VERSION="${DSH_VERSION:-dsh-v0.2.1-rc.2}"
-PNPM_VERSION="${PNPM_VERSION:-11.28.5}"
-IMAGE="${IMAGE:-dsh-web:${DSH_VERSION#dsh-v}}"
-GATEWAY_IMAGE="${GATEWAY_IMAGE:-ghcr.io/sredevopsorg/deepseek-kubernetes-sandbox:gateway}"
-DSH_PORT="${DSH_PORT:-3080}"
-RUN="${RUN:-1}"
-GATEWAY_DIR=examples/dsh-agents-as-a-service/gateway
-
-build_web() {
-  docker build \
-    --build-arg "DSH_VERSION=${DSH_VERSION}" \
-    --build-arg "PNPM_VERSION=${PNPM_VERSION}" \
-    -t "${IMAGE}" \
-    "$@" \
-    .
-}
-
-build_gateway() {
-  docker build -t "${GATEWAY_IMAGE}" "$@" "${GATEWAY_DIR}/"
-}
-
-usage() {
-  echo "usage: $0 [run|web|gateway] [extra docker build args...]" >&2
-  exit 2
-}
+echo "build.sh is deprecated; use 'make image', 'make run' or 'make gateway'." >&2
 
 case "${1:-run}" in
-  run)
-    shift
-    build_web "$@"
-    if [ "${RUN}" = "1" ]; then
-      docker run --rm -it \
-        -p "${DSH_PORT}:3080" \
-        -v dsh-home:/home/node/.dsh \
-        -e DEEPSEEK_API_KEY \
-        "${IMAGE}"
-    fi
-    ;;
-  web)
-    shift
-    build_web "$@"
-    ;;
-  gateway)
-    shift
-    build_gateway "$@"
-    ;;
-  *)
-    usage
-    ;;
+  run) exec make run ;;
+  web) exec make image ;;
+  gateway) exec make gateway ;;
+  *) echo "usage: $0 [run|web|gateway]" >&2; exit 2 ;;
 esac