fix(helm): production-ready Helm chart aligned with ha-raft subsystem

docs/superpowers/specs/2026-04-29-helm-chart-dedicated-repo-design.md

@@ -0,0 +1,156 @@
+# Helm Chart - Dedicated Repository
+
+**Status:** approved
+**Date:** 2026-04-29
+
+---
+
+## Goals
+
+Move the ArcadeDB Helm chart out of the main `arcadedb` monorepo into a dedicated `ArcadeData/arcadedb-helm` repository so that:
+
+- Users can install via standard `helm repo add` without cloning the monorepo
+- The chart is discoverable on Artifact Hub (`helm search hub arcadedb`)
+- The chart has an independent release lifecycle - chart-only fixes do not require a server release
+- A published `index.yaml` is served via GitHub Pages at a stable URL
+
+Out of scope: changes to chart content (done in #4034), Docker Compose scenarios in `arcadedb-deployments`, OCI registry publishing.
+
+---
+
+## Repository Structure
+
+New repo: `ArcadeData/arcadedb-helm`
+
+```
+arcadedb-helm/
+├── charts/
+│   └── arcadedb/          ← chart moved from k8s/helm/ in main repo
+│       ├── Chart.yaml
+│       ├── values.yaml
+│       ├── README.md
+│       └── templates/
+├── index.yaml             ← auto-generated by CI, served via GitHub Pages
+├── README.md              ← helm repo add instructions + Artifact Hub badge
+└── .github/
+    └── workflows/
+        ├── release.yml    ← manual dispatch: bumps version, tags, packages, publishes
+        └── lint.yml       ← runs on every PR and push to main
+```
+
+GitHub Pages is enabled on the `main` branch root (`/`). The stable repository URL is:
+
+```
+https://arcadedata.github.io/arcadedb-helm/
+```
+
+Chart `.tgz` assets are attached to GitHub Releases (not stored in the repo tree). `index.yaml` points at those release asset URLs.
+
+---
+
+## Release Workflow
+
+File: `.github/workflows/release.yml`
+
+**Trigger:** manual `workflow_dispatch` with two inputs:
+
+| Input | Required | Description |
+|---|---|---|
+| `version` | yes | Chart version to release, e.g. `26.5.2` |
+| `app_version` | no | ArcadeDB server version, e.g. `26.5.1`. Leave blank to keep the current `appVersion` in `Chart.yaml`. |
+
+**Steps:**
+
+1. Validate `version` is a valid semver string - fail early with a clear message if not
+2. Update `Chart.yaml`: set `version` to input; set `appVersion` to input if provided
+3. `helm lint charts/arcadedb/` - abort if lint fails
+4. `git commit Chart.yaml -m "chore(helm): release v<version>"`
+5. `git tag v<version>` and push commit + tag
+6. `helm/chart-releaser-action` - packages the chart, updates `index.yaml`, creates GitHub Release with `.tgz` as asset, pushes `index.yaml` to `main`
+
+**To release:**
+
+```
+GitHub → Actions → "Release" → Run workflow → version: 26.5.2 → Run
+```
+
+No manual tagging. No local commands needed.
+
+---
+
+## PR Validation Workflow
+
+File: `.github/workflows/lint.yml`
+
+**Trigger:** push to `main`, all pull requests.
+
+Runs a matrix of `helm template` scenarios to catch regressions:
+
+| Scenario | Key flags |
+|---|---|
+| Default single-node | (none) |
+| HA replicaCount=3 | `--set replicaCount=3` |
+| HPA valid quorum | `--set autoscaling.enabled=true --set autoscaling.minReplicas=3 --set autoscaling.maxReplicas=5` |
+| HPA quorum guard fires | `--set autoscaling.enabled=true --set autoscaling.minReplicas=1 --set autoscaling.maxReplicas=5` (expect failure) |
+| Ingress enabled | `--set ingress.enabled=true` |
+| NetworkPolicy enabled | `--set networkPolicy.enabled=true` |
+
+Plus `helm lint charts/arcadedb/`.
+
+---
+
+## Artifact Hub Registration
+
+One-time manual step after the repo is created and the first chart version is published:
+
+1. Create or log in to an account on [artifacthub.io](https://artifacthub.io)
+2. Add repository: type `Helm`, URL `https://arcadedata.github.io/arcadedb-helm/`
+3. Copy the assigned `repositoryID` UUID
+4. Add to `Chart.yaml`:
+   ```yaml
+   annotations:
+     artifacthub.io/repositoryID: "<uuid>"
+   ```
+5. Commit and include in the first release
+
+After that, every release is auto-indexed within minutes. The chart appears in:
+- `helm search hub arcadedb`
+- Artifact Hub search results
+- Google (Artifact Hub pages rank well for "arcadedb helm chart")
+
+---
+
+## Main Repo Cleanup
+
+In `ArcadeData/arcadedb`:
+
+- Delete `k8s/helm/` entirely
+- Replace with `k8s/README.md`:
+
+```markdown
+# Kubernetes
+
+The ArcadeDB Helm chart has moved to its own repository:
+
+**https://github.com/ArcadeData/arcadedb-helm**
+
+Install:
+
+```bash
+helm repo add arcadedb https://arcadedata.github.io/arcadedb-helm/
+helm repo update
+helm install my-arcadedb arcadedb/arcadedb
+```
+```
+
+- Close issue #4034 with a comment pointing to the new repo (the refactor in that issue seeded the chart content that moves to the new repo)
+- `arcadedb-deployments` is left as-is - no Helm content goes there
+
+---
+
+## Versioning Convention
+
+| Field | Convention |
+|---|---|
+| `Chart.yaml: version` | Independent semver. Bumps for any chart change, including chart-only fixes. Format: matches `appVersion` on server releases, adds patch increments for chart-only fixes (e.g. server `26.5.1` → chart starts at `26.5.1`, chart fix → `26.5.2`). |
+| `Chart.yaml: appVersion` | Tracks the ArcadeDB server release. Updated via the `app_version` workflow input when a new server version ships. |

k8s/README.md

@@ -0,0 +1,13 @@
+# Kubernetes
+
+The ArcadeDB Helm chart has moved to its own repository:
+
+**https://github.com/ArcadeData/arcadedb-helm**
+
+## Install
+
+```bash
+helm repo add arcadedb https://helm.arcadedb.com/
+helm repo update
+helm install my-arcadedb arcadedb/arcadedb
+```