feat(repo)!: repo reorganization (#16)

* 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.

* docs(changelog): generate initial changelog from history

* fix(scripts): make set-version update Dockerfile and sample revision pins

* build(hadolint): document intentional lint exceptions for the main image

---------

Co-authored-by: SREDevOpsAgents <agents@sredevops.org>

scripts/check-versions.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Verify that every version pin in the repository agrees with versions.env.
+# Run by "make check" locally and by the CI lint job.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# shellcheck source=/dev/null
+. ./versions.env
+
+IDENTITY="$DSH_VERSION"
+if [ -n "${RELEASE_REVISION:-}" ]; then
+  IDENTITY="$DSH_VERSION-$RELEASE_REVISION"
+fi
+
+fail=0
+err() { echo "check-versions: $*" >&2; fail=1; }
+expect() { # <file> <literal>
+  if ! grep -Fq -- "$2" "$1"; then
+    err "$1: expected to contain: $2"
+  fi
+}
+
+# Main Dockerfile build args
+expect Dockerfile "ARG DSH_VERSION=$DSH_VERSION"
+expect Dockerfile "ARG PNPM_VERSION=$PNPM_VERSION"
+expect Dockerfile "ARG RELEASE_REVISION=$RELEASE_REVISION"
+
+# Local configuration mirrored for humans
+expect .env.sample "DSH_VERSION=$DSH_VERSION"
+expect .env.sample "PNPM_VERSION=$PNPM_VERSION"
+expect .env.sample "RELEASE_REVISION=$RELEASE_REVISION"
+
+# Image references in the example manifests
+for f in \
+  examples/dsh-agents-as-a-service/manifests/10-sandboxtemplate.yaml \
+  examples/minimal-single-tenant/manifests/sandbox-template.yaml; do
+  expect "$f" "image: $GHCR_IMAGE:$IDENTITY"
+done
+expect examples/dsh-agents-as-a-service/manifests/50-gateway.yaml "image: $GATEWAY_IMAGE:$IDENTITY"
+
+# The gateway image must live below the repository image (one package per
+# example component, no unrelated top-level packages).
+case "$GATEWAY_IMAGE" in
+  "$GHCR_IMAGE"/*) ;;
+  *) err "GATEWAY_IMAGE ($GATEWAY_IMAGE) must be nested below GHCR_IMAGE ($GHCR_IMAGE)" ;;
+esac
+
+# Build tooling must read versions.env instead of hard-coding a version.
+# (scripts/ is excluded: set-version.sh documents usage examples in comments.)
+while IFS= read -r hit; do
+  [ -n "$hit" ] || continue
+  err "hard-coded version outside versions.env: $hit"
+done < <(grep -rnE 'dsh-v[0-9]' .github/workflows Makefile 2>/dev/null || true)
+
+# Prose may mention versions, but only the current identity or its base tag.
+while IFS= read -r token; do
+  [ -n "$token" ] || continue
+  case "$token" in
+    "$IDENTITY"|"$DSH_VERSION") ;;
+    *) err "stale version reference in docs: $token" ;;
+  esac
+done < <(grep -rhoE 'dsh-v[0-9][A-Za-z0-9._-]*' \
+  --include='*.md' --exclude-dir=.git --exclude-dir=.venv --exclude-dir=.uvcache \
+  --exclude=CHANGELOG.md . | sort -u)
+
+if [ "$fail" -ne 0 ]; then
+  echo "check-versions: FAILED" >&2
+  exit 1
+fi
+echo "check-versions: ok ($IDENTITY)"