docs: align readmes, docs and agent guidance with current behavior (#37)

Remove obsolete layout/migration prose and legacy gateway-alias references, reconcile the required-check policy, fix version-label/RBAC/workspace/channel drift, and de-duplicate the example and gateway docs.

Rename the minimal manifest to 10-sandboxtemplate.yaml and mount the dsh-home PVC's workspace subPath at /workspace so the documented persistence is real. Enforce numbered top-level manifests in check-examples.sh.

Verified with make check, yamllint, shellcheck, a Markdown link/anchor scan, and git diff --check.

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -28,7 +28,7 @@ body:
     id: image-tag
     attributes:
       label: Image or release
-      description: The pinned tag or digest, for example dsh-v0.2.1-rc.5.
+      description: The tag or digest you deployed (from the manifest or release metadata).
   - type: input
     id: cluster
     attributes:

.github/pull_request_template.md

@@ -19,8 +19,7 @@
 ## Checklist
 
 - [ ] make check passes (versions, example layout, manifest YAML)
-- [ ] make test passes (gateway unit tests)
-- [ ] make lint passes (ruff, shellcheck; yamllint/actionlint where installed)
+- [ ] make test / make lint pass when the change touches code (gateway unit tests, ruff, shellcheck; yamllint/actionlint where installed)
 - [ ] Docs updated for the change (root README, docs/, example README)
 - [ ] No secrets or usable credentials committed
 - [ ] CHANGELOG.md was not edited by hand (generated by git-cliff)

.github/workflows/ci-manifests.yaml

@@ -1,7 +1,8 @@
 # Manifest shape validation and server-side dry-run. Split from ci.yaml so this
 # job can use native on.pull_request.paths filtering and skip PRs that do not
-# touch manifests, scripts or versions.env. The job name is the required
-# branch-protection check `manifests`.
+# touch manifests, scripts or versions.env. The job name is `manifests`; because
+# it is path-filtered it is an on-demand check, not a required branch-protection
+# check (see docs/gitflow.md).
 name: CI (manifests)
 
 on:

.github/workflows/ci-python.yaml

@@ -1,6 +1,7 @@
 # Gateway unit tests and lint. Split from ci.yaml so this job can use native
 # on.pull_request.paths filtering and skip PRs that do not touch the gateway.
-# The job name is the required branch-protection check `python`.
+# The job name is `python`; because it is path-filtered it is an on-demand check,
+# not a required branch-protection check (see docs/gitflow.md).
 name: CI (python)
 
 on:

.github/workflows/release.yaml

@@ -16,11 +16,6 @@ on:
         description: Existing tag to release (must match versions.env)
         required: true
         type: string
-      publish_legacy_gateway_alias:
-        description: Also publish the legacy :gateway alias (one release only)
-        required: false
-        default: true
-        type: boolean
 
 permissions:
   contents: write
@@ -193,28 +188,6 @@ jobs:
         ${{ needs.meta.outputs.gateway_image }}:${{ needs.meta.outputs.identity }}
         ${{ needs.meta.outputs.gateway_image }}:latest
 
-  legacy-gateway-alias:
-    name: Publish legacy :gateway alias (temporary)
-    needs: [meta, build-gateway]
-    if: github.event_name != 'workflow_dispatch' || inputs.publish_legacy_gateway_alias
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Retag gateway as the legacy package tag
-        env:
-          SOURCE: ${{ needs.meta.outputs.gateway_image }}:${{ needs.meta.outputs.identity }}
-          LEGACY: ${{ needs.meta.outputs.ghcr_image }}:gateway
-        run: |
-          set -euo pipefail
-          docker buildx imagetools create -t "$LEGACY" "$SOURCE"
-          echo "Deprecated alias $LEGACY now points at $SOURCE" >> "$GITHUB_STEP_SUMMARY"
-
   publish-release:
     name: Changelog and GitHub Release
     needs: [meta, build-main, build-gateway]