docs(deploy): state-hub Forgejo image promote flow (CUST-WP-0059 T06)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

deploy/railiance/apps/charts/state-hub/PROMOTE.md

@@ -0,0 +1,39 @@
+# state-hub image promotion (Forgejo)
+
+The state-hub container image is built and published by CI
+(`.forgejo/workflows/image.yaml`) to the **Forgejo** registry on every `main`
+push that touches the app:
+
+- `forgejo.coulomb.social/coulomb/state-hub:main-<short-sha>` — immutable, promotable
+- `forgejo.coulomb.social/coulomb/state-hub:latest` — moving pointer to newest main
+
+The chart's `image.repository` defaults to `forgejo.coulomb.social/coulomb/state-hub`.
+
+## Promote a build to the cluster
+
+1. Pick a CI-produced tag to promote — **use an immutable `main-<sha>`**, not
+   `latest` (avoid surprise upgrades). List candidates:
+   ```
+   # requires a Forgejo read token
+   curl -s -u <user>:<token> \
+     "https://forgejo.coulomb.social/api/v1/packages/coulomb?type=container&q=state-hub"
+   ```
+2. Upgrade the release (rolling, `maxUnavailable=0` → zero downtime; `--atomic`
+   auto-rolls-back if the pull fails):
+   ```
+   helm -n state-hub upgrade state-hub <chart-path> \
+     --reuse-values \
+     --set image.tag=main-<sha> \
+     --atomic --timeout 3m
+   ```
+3. Update this chart's `appVersion` to the promoted `main-<sha>` and commit, so the
+   declared version matches what's deployed.
+
+## History
+
+- **2026-07-16:** the deployed release pinned the gitea-era tag `f2e042a`, which
+  Forgejo CI never produced. The running image was preserved by a one-off
+  gitea→Forgejo copy of `f2e042a` and the release repointed to Forgejo
+  (CUST-WP-0059). Going forward, promotions use CI `main-<sha>` tags — no manual
+  image copies. The next promotion should move off `f2e042a` onto a `main-<sha>`
+  and update `appVersion` accordingly.