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.

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thanks for improving deepseek-kubernetes-sandbox. This repository packages
+DeepSeek Harness Web as a container and ships self-contained implementation
+examples around it. The root is the container; every implementation lives
+under examples/.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| Dockerfile | The primary artifact: the DSH Web image |
+| versions.env | Single source of truth for every pinned version |
+| Makefile | Canonical local entrypoint (build, test, lint, check, e2e) |
+| docs/ | Repository-wide docs: main image, example contract, gitflow, versioning |
+| examples/ | One self-contained implementation per directory |
+| scripts/ | Repository checks (versions, example layout, manifests, version bump) |
+| .github/ | CI, releases, dependency updates, templates |
+
+## Requirements
+
+- Docker (for image builds)
+- Python 3.12+ (gateway tests and repository checks)
+- make and git
+- kubectl and kind only for the end-to-end example
+
+## Local workflow
+
+    git switch -c feat/<short-slug>
+    make check          # versions, example layout, manifest YAML
+    make test           # gateway unit tests
+    make lint           # ruff, shellcheck (+ yamllint/actionlint when installed)
+    make image          # build the main DSH Web image
+    make gateway        # build the example gateway image
+    make e2e            # full kind walkthrough (optional, slow)
+
+Install the gateway dev dependencies once:
+
+    python -m pip install -r examples/dsh-agents-as-a-service/gateway/requirements-dev.txt
+
+## Pull requests
+
+- Use a Conventional Commit title, for example feat(gateway): add wake metrics
+  or docs(examples): clarify SSO trust boundary. PR titles are linted.
+- Keep the diff scoped. Squash merge into main; history stays linear.
+- Required checks: lint, python, manifests, gateway-image, pr-title, CodeQL,
+  and dependency-review. Branch protection is described in docs/gitflow.md.
+- Update the docs that the change affects; docs are part of the change, not a
+  follow-up.
+- Never commit a real secret. Secret-shaped YAML belongs in a *.yaml.example
+  file, and versions live in versions.env only.
+
+## Changing versions
+
+    make set-version DSH_VERSION=dsh-vX.Y.Z RELEASE_REVISION=r2
+    make check
+
+CHANGELOG.md is generated by git-cliff from Conventional Commits. Do not edit
+it by hand; the release workflow regenerates it.
+
+## Adding an example
+
+Read docs/examples.md, then add examples/<name>/ with:
+
+- README.md (what it demonstrates, prerequisites, steps, teardown)
+- manifests/NN-*.yaml (numbered, plain kubectl)
+- optional manifests/exposure/<variant>/ with its own README.md
+- optional components (a Dockerfile plus README and tests per component)
+- scripts/ with executable, idempotent, self-cleaning scripts
+- docs/ for deeper material
+
+List it in examples/README.md. scripts/check-examples.sh enforces this layout.
+
+## Documentation
+
+- Root README.md is the front door: main image first, then examples.
+- docs/ holds repository-wide material; example-specific material belongs in
+  the example directory.
+
+## Branches and releases
+
+See docs/gitflow.md for the branch model and docs/versioning.md for the
+release identity, channels and rollback rules.
+
+## Security
+
+See SECURITY.md. Report vulnerabilities privately through GitHub Security
+Advisories; do not open a public issue.