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>

docs/gitflow.md

@@ -0,0 +1,128 @@
+# Gitflow: branches, pull requests and CI
+
+This repository uses **trunk-based development with release branches**. `main` is
+always releasable; feature work happens on short-lived branches; releases are cut
+from `main` onto a release branch and tagged with an immutable release identity.
+See [versioning](versioning.md) for what the tags mean.
+
+## Branches
+
+| Branch | Branched from | Merged into | Purpose |
+| --- | --- | --- | --- |
+| `main` | — | — | The integration trunk. Protected, linear history, always releasable. |
+| `feat/<slug>` | `main` | `main` (squash) | New capability or example. |
+| `fix/<slug>` | `main` | `main` (squash) | Bug fix. |
+| `docs/<slug>` | `main` | `main` (squash) | Documentation only. |
+| `refactor/<slug>`, `chore/<slug>`, `test/<slug>` | `main` | `main` (squash) | Non-behavioral rework, maintenance, tests. |
+| `release/<identity>` | `main` at the release commit | — | Release stabilization and tagging. Only release-blocking fixes land here. |
+| `hotfix/<slug>` | The release branch (or the tagged commit) | `main` and the release branch | Urgent production fix. |
+
+Keep branches short-lived. Rebase on `main` rather than merging `main` into the
+branch; the PR is squash-merged, so individual branch commits are never part of
+`main` history.
+
+## Pull requests
+
+1. **One scoped change per PR.** Do not mix a version bump with unrelated work,
+   and update the docs the change touches in the same PR.
+2. **Conventional PR title.** The title becomes the squash commit message, so it
+   is linted by the `pr-title` check: `feat(scope): ...`, `fix(scope): ...`,
+   `docs(scope): ...`, `build: ...`, `ci: ...`, `refactor: ...`, `test: ...`,
+   `chore: ...`. Breaking changes use `feat(scope)!: ...` or a
+   `BREAKING CHANGE:` footer.
+3. **CI must be green.** All required checks below must pass before merge.
+4. **Squash merge only.** `main` stays linear and protected; merged PRs are one
+   commit each.
+5. **No direct pushes to `main`** or to a release branch. Both are protected.
+6. **Review for behavior changes.** Infrastructure, workflow, release and
+   gateway-contract changes need a maintainer review; trivial docs changes still
+   need the checks.
+
+## Required checks
+
+| Check | Workflow / job | What it verifies |
+| --- | --- | --- |
+| `lint` | `ci.yaml` | `scripts/check-versions.sh` (version pins and markdown tokens), ruff on the gateway, shellcheck on shell scripts, yamllint/actionlint when available. |
+| `python` | `ci.yaml` | Gateway unit tests (`pytest`). |
+| `manifests` | `ci.yaml` | `scripts/check-examples.sh`, `scripts/check-manifests.py` and a server-side dry-run of every example manifest against the agent-sandbox CRDs. |
+| `gateway-image` | `ci.yaml` | Builds the gateway image and smoke-tests `/healthz` without a cluster. |
+| `pr-title` | `pr-title.yaml` | Conventional Commit PR title. |
+| `CodeQL` | `codeql.yml` | Static analysis for Python and GitHub Actions. |
+| `dependency-review` | `ci.yaml` | Dependency changes introduced by the PR (job `dependency-review`; runs on pull requests only). |
+
+The image build workflows (`_build-image.yaml`, `build-main.yaml`,
+`build-gateway.yaml`) and `e2e-kind.yaml` are **not** required on every PR: the
+image builds run where they are needed, and the kind end-to-end suite is reserved
+for release validation and manual dispatch because it is slow.
+
+## Releases
+
+Releases are cut from `main`:
+
+1. Confirm `main` is green and `make check`, `make test`, `make lint` pass.
+2. Bump [versions.env](../versions.env) if the DSH ref changed, using
+   `make set-version`; otherwise keep the same `DSH_VERSION` and bump
+   `RELEASE_REVISION`.
+3. Create `release/<identity>` from the release commit.
+4. Run `make release-dry-run` and review the generated notes.
+5. Create and push the annotated `dsh-*` release tag. The `release.yaml`
+   workflow validates that the tag matches [versions.env](../versions.env), builds
+   and pushes the multi-arch images (version + latest), creates the GitHub
+   Release from the git-cliff notes, and opens a `chore(changelog)` PR that
+   refreshes `CHANGELOG.md` on `main`.
+6. Merge the changelog PR and any release-branch-only fixes back to `main`.
+
+Full procedure: [versioning](versioning.md).
+
+## Hotfixes
+
+A released tag is **never** moved or re-tagged — tags and image identities are
+immutable. To fix a broken release:
+
+1. Branch `hotfix/<slug>` from the release tag (or its release branch).
+2. Make the minimal fix, add a test, open a PR; the same required checks apply.
+3. Publish a new identity with a higher `RELEASE_REVISION` (`-r(N+1)`). Do not
+   reuse or delete the broken tag.
+4. Merge the fix back into `main` (or cherry-pick it) so the trunk is fixed too.
+
+Rollback is also a re-release, never a retag: see
+[versioning](versioning.md#rollback).
+
+## Tag protection
+
+All release tags match `dsh-*` and are protected:
+
+- only maintainers (the release workflow) may create them;
+- they cannot be deleted or force-updated;
+- they are annotated and point at the release commit on a release branch.
+
+Image tags derive from the same identity and are equally immutable; the mutable
+`latest` and `main` image channels always point at a release or a trunk build
+respectively.
+
+## One-time GitHub settings checklist
+
+Configure these on the repository before relying on the workflow:
+
+- [ ] **Branches → main**: require a pull request; require the checks `lint`,
+      `python`, `manifests`, `gateway-image`, `pr-title`, `CodeQL`,
+      `dependency-review`; require branches to be up to date; require conversation
+      resolution; restrict direct pushes; allow only squash merges and enable
+      "Automatically delete head branches".
+- [ ] **Branches → release/***: same protections, plus allow the release workflow
+      to push tags.
+- [ ] **Tags → dsh-***: restrict creation/update/deletion to maintainers; a tag
+      push triggers the release workflow.
+- [ ] **Actions → General**: allow GitHub Actions; set workflow permissions to
+      read-only by default; allow `GITHUB_TOKEN` to create pull requests only
+      where required.
+- [ ] **Actions → Runners**: make the arm64 runners (`ubuntu-24.04-arm`) available
+      to the public/private repository as appropriate.
+- [ ] **Packages**: grant the release workflow `packages: write` (workflow
+      permissions do this) and protect the
+      `ghcr.io/sredevopsorg/deepseek-kubernetes-sandbox` packages from deletion.
+- [ ] **Security**: enable CodeQL default setup **or** keep the advanced
+      `codeql.yml` workflow (not both), enable Dependabot alerts and
+      dependency review.
+- [ ] **Secrets/Variables**: none are needed for image publishing; the workflows
+      use `GITHUB_TOKEN`.