docs(migration): bedag/raw → base release ownership transfer script

[bussyjd]

Summary

PR #523 relocates 6 bedag/raw helmfile releases into the base chart so the
stack has one source of truth for what ships in the erpc, obol-frontend,
and llm namespaces. Fresh installs are unaffected. Clusters created before
PR #523 fail at helm upgrade base with invalid ownership metadata because
Helm refuses to adopt resources owned by another release.

This PR ships a one-shot migration script and operator documentation so
existing clusters can be upgraded without hand-fixing ~10 resources.

Symptom

Error: UPGRADE FAILED: <resource> exists and cannot be imported into the
current release: invalid ownership metadata; annotation validation error:
key "meta.helm.sh/release-name" must equal "base"; current value is
"<legacy-release>"

Before / After

BEFORE (pre-#523 cluster after upgrade attempt)
  helmfile.yaml:
    - obol-frontend-rbac     (bedag/raw)  ──┐
    - obol-frontend-httproute (bedag/raw)   │
    - erpc-httproute         (bedag/raw)   ├─ each owns its own resources
    - erpc-x402-middleware   (bedag/raw)   │  with meta.helm.sh/release-name
    - erpc-metadata          (bedag/raw)   │  ≠ "base"
    - llm-buyer-podmonitor   (bedag/raw)  ──┘
  base chart upgrade ─► invalid ownership metadata, abort.

AFTER (script run, then obol stack up)
  All resources annotated:
    meta.helm.sh/release-name=base
    meta.helm.sh/release-namespace=kube-system
    app.kubernetes.io/managed-by=Helm
  base chart upgrade ─► clean adoption, helm upgrade succeeds.

When to run

• Once, before obol stack up, against any cluster created before
  PR refactor: relocate remaining bedag/raw helmfile releases into base chart #523 merges.
• Script is idempotent — safe to re-run.
• Fresh installs do not need it.

bash hack/migrate-bedag-raw-to-base.sh
obol stack up

Releases handled

Legacy release	Namespace
obol-frontend-rbac	obol-frontend
obol-frontend-httproute	obol-frontend
erpc-httproute	erpc
erpc-x402-middleware	erpc
erpc-metadata	erpc
llm-buyer-podmonitor	llm
x402-verifier-podmonitor	x402 (partial-upgrade clusters from before PR #513)

Plus three resources that may exist with no Helm ownership at all and need
to be adopted into base: namespace/erpc, namespace/obol-frontend,
prometheusrule/x402-verifier.

Files

• hack/migrate-bedag-raw-to-base.sh — the migration script (executable).
• docs/upgrade-from-pre-pr-523.md — operator-facing upgrade guide.
• .github/release-template.md — release-notes entry under
  Breaking changes / Migration notes pointing future release authors at the
  script.

Test plan

• bash -n hack/migrate-bedag-raw-to-base.sh (syntax check) passes.
• Script was executed manually during the 14-PR integration test campaign
  against a pre-refactor: relocate remaining bedag/raw helmfile releases into base chart #523 cluster and confirmed to unblock obol stack up — every
  invalid ownership metadata failure resolved on the next upgrade.
• Re-run a second time on the same cluster to confirm idempotency
  (every resource reports already on base, skipping).
• On a fresh cluster, confirm the script is a no-op (no orphan releases
  found) and does not affect obol stack up.

Surfaced by the 14-PR integration test campaign; see
plans/integration-test-results-final-20260524.md Bug #2.

[bussyjd]

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.