From 41f5149c156f7faaa319ef30537264483ccd9348 Mon Sep 17 00:00:00 2001
From: Nik Matthiopoulos <nikolaos.matthiopoulos@solo.io>
Date: Wed, 11 Mar 2026 19:49:06 -0700
Subject: [PATCH 1/3] update charts.yaml version for release

---
 .github/workflows/release.yml                 | 120 ++++--------------
 .gitignore                                    |   3 +
 Makefile                                      |  80 +++++++-----
 .../{Chart.yaml => Chart-template.yaml}       |   9 +-
 4 files changed, 80 insertions(+), 132 deletions(-)
 rename charts/agentregistry/{Chart.yaml => Chart-template.yaml} (76%)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4662ee20..8b62e2d4 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -82,121 +82,49 @@ jobs:
       with:
         go-version-file: "go.mod"
 
-    - name: Resolve chart version
-      id: version
+    - name: Resolve version
       run: |
-        set -euo pipefail
-        CHART_VER=$(grep -E '^version:' charts/agentregistry/Chart.yaml | awk '{print $2}' | tr -d '"')
-        echo "chart_version=${CHART_VER}" >> "$GITHUB_OUTPUT"
-
-        if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-          TARGET_VER="${{ github.event.inputs.version }}"
+        if [ -n "${{ github.event.inputs.version }}" ]; then
+          echo "VERSION=${{ github.event.inputs.version }}" >> "$GITHUB_ENV"
         else
-          TARGET_VER="${GITHUB_REF#refs/tags/}"
-          TARGET_VER="${TARGET_VER#v}"
-        fi
-        echo "target_version=${TARGET_VER}" >> "$GITHUB_OUTPUT"
-        echo "Chart.yaml version : ${CHART_VER}"
-        echo "Target publish version: ${TARGET_VER}"
-
-    - name: Verify Chart.yaml version matches release version
-      run: |
-        set -euo pipefail
-        CHART_VER="${{ steps.version.outputs.chart_version }}"
-        TARGET_VER="${{ steps.version.outputs.target_version }}"
-        if [ "$CHART_VER" != "$TARGET_VER" ]; then
-          echo "::error::Chart.yaml version (${CHART_VER}) does not match release version (${TARGET_VER})."
-          echo "Update charts/agentregistry/Chart.yaml to version: ${TARGET_VER} before releasing."
-          exit 1
+          echo "VERSION=$(echo "$GITHUB_REF" | cut -c12-)" >> "$GITHUB_ENV"
         fi
-        echo "Version check passed: ${CHART_VER}"
 
     - name: Cache Helm plugins
       uses: actions/cache@v4
       with:
         path: ~/.local/share/helm/plugins
-        # Cache the helm-unittest plugin by plugin version so it's stable across chart changes
         key: ${{ runner.os }}-helm-plugins-unittest-${{ env.HELM_PLUGIN_UNITTEST_VERSION }}
         restore-keys: |
           ${{ runner.os }}-helm-plugins-unittest-
 
-    - name: Ensure helm-unittest plugin (Makefile)
-      run: |
-        set -euo pipefail
-        make helm-unittest-install
-
-    - name: Lint chart (Makefile)
-      run: make charts-lint HELM_CHART_DIR=charts/agentregistry
-
-    - name: Run chart tests (Makefile)
-      run: make charts-test HELM_CHART_DIR=charts/agentregistry
-
     - name: Build Release Artifacts
       env:
-        DOCKER_REGISTRY: "ghcr.io" # prod for releases
-      run: |
-        # if workflow_dispatch is used, use the version input
-        if [ -n "${{ github.event.inputs.version }}" ]; then
-          export VERSION=${{ github.event.inputs.version }}
-        else
-          export VERSION=$(echo "$GITHUB_REF" | cut -c12-)
-        fi
-        make release-cli
+        DOCKER_REGISTRY: "ghcr.io"
+      run: make release-cli
 
-    - name: Package chart
-      run: |
-        set -euo pipefail
-        mkdir -p build/charts
-        helm package charts/agentregistry -d build/charts
-        echo "--- packaged files ---"
-        ls -lh build/charts/
-
-    - name: Generate checksum
-      run: |
-        set -euo pipefail
-        cd build/charts
-        sha256sum ./*.tgz > checksums.txt
-        cat checksums.txt
-
-    - name: Resolve registry credentials
-      id: creds
-      run: |
-        # Use explicit secret if provided; fall back to built-in GITHUB_TOKEN.
-        if [ -n "${{ secrets.HELM_REGISTRY_PASSWORD }}" ]; then
-          echo "password_source=secret" >> "$GITHUB_OUTPUT"
-        else
-          echo "password_source=github_token" >> "$GITHUB_OUTPUT"
-        fi
-
-    - name: Log in to GHCR (OCI registry)
+    - name: Log in to Helm registry
+      env:
+        HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
+        HELM_REGISTRY_USERNAME: ${{ secrets.HELM_REGISTRY_USERNAME || github.actor }}
+        HELM_REGISTRY_PASSWORD: ${{ secrets.HELM_REGISTRY_PASSWORD || secrets.GITHUB_TOKEN }}
       run: |
         set -euo pipefail
-        REGISTRY="${{ secrets.HELM_REGISTRY || 'ghcr.io' }}"
-        USERNAME="${{ secrets.HELM_REGISTRY_USERNAME || github.actor }}"
-
-        if [ "${{ steps.creds.outputs.password_source }}" = "secret" ]; then
-          PASSWORD="${{ secrets.HELM_REGISTRY_PASSWORD }}"
-        else
-          PASSWORD="${{ secrets.GITHUB_TOKEN }}"
-        fi
-
-        printf "%s" "${PASSWORD}" | helm registry login "${REGISTRY}" \
-          --username "${USERNAME}" \
+        printf "%s" "${HELM_REGISTRY_PASSWORD}" | helm registry login "${HELM_REGISTRY}" \
+          --username "${HELM_REGISTRY_USERNAME}" \
           --password-stdin
-        echo "Logged in to ${REGISTRY} as ${USERNAME}"
 
-    - name: Push chart to GHCR
-      run: |
-        set -euo pipefail
-        REGISTRY="${{ secrets.HELM_REGISTRY || 'ghcr.io' }}"
-        REPO="${{ secrets.HELM_REPO || 'agentregistry-dev/agentregistry' }}"
-        CHART_VER="${{ steps.version.outputs.chart_version }}"
-
-        for pkg in build/charts/*.tgz; do
-          [ -f "$pkg" ] || continue
-          echo "Pushing ${pkg} → oci://${REGISTRY}/${REPO}/charts/agentregistry:${CHART_VER}"
-          helm push "${pkg}" "oci://${REGISTRY}/${REPO}/charts"
-        done
+    - name: Release Helm chart
+      env:
+        HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
+        HELM_REPO: ${{ secrets.HELM_REPO || 'agentregistry-dev/agentregistry' }}
+      run: make release-helm
+
+    - name: Log out of Helm registry
+      if: always()
+      env:
+        HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
+      run: helm registry logout "${HELM_REGISTRY}" || true
 
 
     - name: Create GitHub Release
diff --git a/.gitignore b/.gitignore
index 4333a0d2..cf9617fd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,6 @@ Thumbs.db
 .env.staging
 .env.production
 
+# Generated Helm chart manifest
+charts/agentregistry/Chart.yaml
+
diff --git a/Makefile b/Makefile
index 57b63bd7..9e1c7206 100644
--- a/Makefile
+++ b/Makefile
@@ -35,12 +35,12 @@ LOCALARCH ?= $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
 ## Helm / Chart settings
 # Override HELM if your helm binary lives elsewhere (e.g. HELM=/usr/local/bin/helm).
 HELM ?= helm
+# CHART_VERSION strips the leading 'v' from VERSION for use in Chart.yaml (Helm requires semver without the prefix).
+CHART_VERSION ?= $(shell echo $(VERSION) | sed 's/^v//')
 HELM_CHART_DIR ?= ./charts/agentregistry
 HELM_PACKAGE_DIR ?= build/charts
 HELM_REGISTRY ?= ghcr.io
 HELM_REPO ?= agentregistry-dev/agentregistry
-# HELM_PUSH_MODE: oci (default, recommended) | repo (legacy chart repo / ChartMuseum)
-HELM_PUSH_MODE ?= oci
 HELM_PLUGIN_UNITTEST_URL ?= https://github.com/helm-unittest/helm-unittest
 # Pin the helm-unittest plugin version for reproducibility and allow install flags
 HELM_PLUGIN_UNITTEST_VERSION ?= v1.0.3
@@ -309,7 +309,7 @@ install-postgresql: ## Deploy standalone PostgreSQL/pgvector into the Kind clust
 BUILD ?= true
 
 .PHONY: install-agentregistry
-install-agentregistry: ## Build images and Helm install AgentRegistry into the Kind cluster (BUILD=false to skip image builds)
+install-agentregistry: charts-generate ## Build images and Helm install AgentRegistry into the Kind cluster (BUILD=false to skip image builds)
 ifeq ($(BUILD),true)
 install-agentregistry: docker-server docker-agentgateway
 endif
@@ -412,6 +412,23 @@ _helm-check:
 	  exit 1; \
 	fi
 
+# Generate Chart.yaml from Chart-template.yaml using envsubst.
+.PHONY: charts-generate
+charts-generate: ## Generate Chart.yaml from Chart-template.yaml (uses CHART_VERSION, default derived from git tags)
+	@echo "Generating $(HELM_CHART_DIR)/Chart.yaml (version=$(CHART_VERSION))..."
+	CHART_VERSION=$(CHART_VERSION) envsubst '$$CHART_VERSION' \
+	  < $(HELM_CHART_DIR)/Chart-template.yaml \
+	  > $(HELM_CHART_DIR)/Chart.yaml
+
+# Package the chart, generating Chart.yaml from the template first.
+.PHONY: charts-package
+charts-package: charts-generate ## Generate Chart.yaml and package the Helm chart into $(HELM_PACKAGE_DIR)
+	@mkdir -p $(HELM_PACKAGE_DIR)
+	@echo "Packaging chart $(HELM_CHART_DIR) → $(HELM_PACKAGE_DIR)/"
+	$(HELM) package $(HELM_CHART_DIR) -d $(HELM_PACKAGE_DIR)
+	@echo "Packaged chart(s):"
+	@ls -1 $(HELM_PACKAGE_DIR)/*.tgz
+
 # Build chart dependencies (resolves Chart.yaml dependencies → charts/ subdir).
 .PHONY: charts-deps
 charts-deps: _helm-check ## Build Helm chart dependencies
@@ -420,7 +437,7 @@ charts-deps: _helm-check ## Build Helm chart dependencies
 
 # Lint chart with --strict so warnings are treated as errors.
 .PHONY: charts-lint
-charts-lint: charts-deps ## Lint the Helm chart with --strict
+charts-lint: charts-generate charts-deps ## Lint the Helm chart with --strict
 	@echo "Linting Helm chart $(HELM_CHART_DIR)..."
 	$(HELM) lint $(HELM_CHART_DIR) --strict
 
@@ -444,32 +461,35 @@ charts-package: charts-lint ## Package the Helm chart into $(HELM_PACKAGE_DIR)
 	@echo "Packaged chart(s):"
 	@ls -1 $(HELM_PACKAGE_DIR)/*.tgz
 
-# Push packaged chart(s) to an OCI registry.
-# Credentials are read from the environment at runtime (never stored in the Makefile):
-#   HELM_REGISTRY_USERNAME   – registry username (default: your shell $USER)
-#   HELM_REGISTRY_PASSWORD   – registry password / token (required)
-# Override registry/repo: make charts-push HELM_REGISTRY=ghcr.io HELM_REPO=org/repo
+# Internal: push pre-packaged chart. Does NOT login or package first.
+# Caller is responsible for authenticating with the registry before invoking this target.
+# Override registry/repo: make _helm-push HELM_REGISTRY=ghcr.io HELM_REPO=org/repo
+.PHONY: _helm-push
+_helm-push: _helm-check
+	@echo "Pushing $(HELM_PACKAGE_DIR)/agentregistry-$(CHART_VERSION).tgz → oci://$(HELM_REGISTRY)/$(HELM_REPO)/charts"
+	$(HELM) push "$(HELM_PACKAGE_DIR)/agentregistry-$(CHART_VERSION).tgz" "oci://$(HELM_REGISTRY)/$(HELM_REPO)/charts"
+
+# Push packaged chart to an OCI registry (packages first). Caller must be logged in.
 .PHONY: charts-push
-charts-push: charts-package ## Push packaged charts to the configured registry
-	@echo "Pushing chart(s) to $(HELM_REGISTRY)/$(HELM_REPO)/charts (mode: $(HELM_PUSH_MODE))"
-ifeq ($(HELM_PUSH_MODE),oci)
-	@if [ -z "$$HELM_REGISTRY_PASSWORD" ]; then \
-	  echo "ERROR: HELM_REGISTRY_PASSWORD is not set. Export it before running this target."; \
-	  exit 1; \
-	fi
-	@printf "%s" "$$HELM_REGISTRY_PASSWORD" | $(HELM) registry login $(HELM_REGISTRY) \
-	  --username "$${HELM_REGISTRY_USERNAME:-$$USER}" \
-	  --password-stdin
-	@for pkg in $(HELM_PACKAGE_DIR)/*.tgz; do \
-	  [ -f "$$pkg" ] || continue; \
-	  echo "  Pushing $$pkg → oci://$(HELM_REGISTRY)/$(HELM_REPO)/charts"; \
-	  $(HELM) push "$$pkg" "oci://$(HELM_REGISTRY)/$(HELM_REPO)/charts"; \
-	done
-	@$(HELM) registry logout $(HELM_REGISTRY) || true
-else
-	@echo "Non-OCI push (mode=$(HELM_PUSH_MODE)) — implement repo-specific push logic or use chart-releaser."
-	@exit 1
-endif
+charts-push: charts-package _helm-push ## Package and push chart to the configured registry
+
+# Generate SHA-256 checksums for all packaged chart files.
+.PHONY: charts-checksum
+charts-checksum: ## Generate SHA-256 checksum for the packaged chart in $(HELM_PACKAGE_DIR)
+	sha256sum "$(HELM_PACKAGE_DIR)/agentregistry-$(CHART_VERSION).tgz" > "$(HELM_PACKAGE_DIR)/checksums.txt"
+	@echo "--- checksum ---"
+	@cat $(HELM_PACKAGE_DIR)/checksums.txt
+
+# Full Helm release pipeline: generate Chart.yaml → lint → test → package → checksum → push.
+# Required env vars for the push step: HELM_REGISTRY_PASSWORD (and optionally HELM_REGISTRY_USERNAME).
+# Override version: make release-helm CHART_VERSION=1.2.3
+.PHONY: release-helm
+release-helm: ## Full Helm release: generate Chart.yaml, lint, test, package, checksum, and push
+	$(MAKE) charts-lint
+	$(MAKE) charts-test
+	$(MAKE) charts-package
+	$(MAKE) charts-checksum
+	$(MAKE) _helm-push
 
 # Run helm-unittest against charts/agentregistry/tests/*.
 # This target:
@@ -477,7 +497,7 @@ endif
 #   2. checks for the helm-unittest plugin and installs it if missing
 #   3. runs the full test suite
 .PHONY: charts-test
-charts-test: _helm-check charts-deps helm-unittest-install ## Run helm-unittest chart tests
+charts-test: charts-generate _helm-check charts-deps helm-unittest-install ## Run helm-unittest chart tests
 	@echo "Running helm-unittest on $(HELM_CHART_DIR)..."
 	$(HELM) unittest $(HELM_CHART_DIR) --file "tests/*_test.yaml"
 
diff --git a/charts/agentregistry/Chart.yaml b/charts/agentregistry/Chart-template.yaml
similarity index 76%
rename from charts/agentregistry/Chart.yaml
rename to charts/agentregistry/Chart-template.yaml
index d33a8949..ed1cf897 100644
--- a/charts/agentregistry/Chart.yaml
+++ b/charts/agentregistry/Chart-template.yaml
@@ -2,8 +2,8 @@ apiVersion: v2
 name: agentregistry
 description: Production-grade Helm chart for Agent Registry -- deploy, secure, and scale the open-source platform for curating and managing AI agents, MCP servers, and skills on Kubernetes with bundled PostgreSQL/pgvector
 type: application
-version: 0.3.0
-appVersion: "0.3.0"
+version: ${CHART_VERSION}
+appVersion: "${CHART_VERSION}"
 kubeVersion: ">=1.19.0-0"
 keywords:
   - agentregistry
@@ -13,7 +13,6 @@ keywords:
   - ai
   - llm
 home: https://github.com/agentregistry-dev/agentregistry
-icon: https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/icon.png
 sources:
   - https://github.com/agentregistry-dev/agentregistry
 maintainers:
@@ -26,6 +25,4 @@ annotations:
       url: https://github.com/agentregistry-dev/agentregistry
   artifacthub.io/images: |
     - name: agentregistry
-      image: ghcr.io/agentregistry-dev/agentregistry/server:0.2.1
-    - name: pgvector
-      image: pgvector/pgvector:0.8.2-pg16
+      image: ghcr.io/agentregistry-dev/agentregistry/server:${CHART_VERSION}

From e802fadfd95c890e4d0d8504c25e14ba2d9016ad Mon Sep 17 00:00:00 2001
From: Nik Matthiopoulos <nikolaos.matthiopoulos@solo.io>
Date: Thu, 12 Mar 2026 09:35:40 -0700
Subject: [PATCH 2/3] more cleanup

---
 .github/workflows/release.yml | 48 +++++++++++------------------------
 1 file changed, 15 insertions(+), 33 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8b62e2d4..7e2e51fb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -9,6 +9,10 @@ on:
       version:
         description: 'Version number'
 
+env:
+  VERSION: ${{ github.event.inputs.version || github.ref_name }}
+  DOCKER_REGISTRY: ghcr.io
+
 jobs:
   docker:
     strategy:
@@ -37,7 +41,7 @@ jobs:
     - name: Login to GitHub Container Registry
       uses: docker/login-action@v3
       with:
-        registry: ghcr.io
+        registry: ${{ env.DOCKER_REGISTRY }}
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
@@ -53,15 +57,7 @@ jobs:
       env:
         DOCKER_BUILD_ARGS: "--push --platform linux/amd64,linux/arm64"
         DOCKER_BUILDER: "docker buildx"
-        DOCKER_REGISTRY: "ghcr.io" # prod for releases, local for dev
-      run: |
-        # if workflow_dispatch is used, use the version input
-        if [ -n "${{ github.event.inputs.version }}" ]; then
-          export VERSION=${{ github.event.inputs.version }}
-        else
-          export VERSION=$(echo "$GITHUB_REF" | cut -c12-)
-        fi
-        make docker-${{ matrix.image }}
+      run: make docker-${{ matrix.image }}
 
   release:
     needs:
@@ -69,6 +65,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       HELM_PLUGIN_UNITTEST_VERSION: v1.0.3
+      HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
+      HELM_REPO: ${{ secrets.HELM_REPO || 'agentregistry-dev/agentregistry' }}
     permissions:
       contents: write
       packages: write
@@ -82,14 +80,6 @@ jobs:
       with:
         go-version-file: "go.mod"
 
-    - name: Resolve version
-      run: |
-        if [ -n "${{ github.event.inputs.version }}" ]; then
-          echo "VERSION=${{ github.event.inputs.version }}" >> "$GITHUB_ENV"
-        else
-          echo "VERSION=$(echo "$GITHUB_REF" | cut -c12-)" >> "$GITHUB_ENV"
-        fi
-
     - name: Cache Helm plugins
       uses: actions/cache@v4
       with:
@@ -98,14 +88,9 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-helm-plugins-unittest-
 
-    - name: Build Release Artifacts
-      env:
-        DOCKER_REGISTRY: "ghcr.io"
-      run: make release-cli
 
     - name: Log in to Helm registry
       env:
-        HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
         HELM_REGISTRY_USERNAME: ${{ secrets.HELM_REGISTRY_USERNAME || github.actor }}
         HELM_REGISTRY_PASSWORD: ${{ secrets.HELM_REGISTRY_PASSWORD || secrets.GITHUB_TOKEN }}
       run: |
@@ -114,19 +99,12 @@ jobs:
           --username "${HELM_REGISTRY_USERNAME}" \
           --password-stdin
 
+    - name: Build Release Artifacts
+      run: make release-cli
+
     - name: Release Helm chart
-      env:
-        HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
-        HELM_REPO: ${{ secrets.HELM_REPO || 'agentregistry-dev/agentregistry' }}
       run: make release-helm
 
-    - name: Log out of Helm registry
-      if: always()
-      env:
-        HELM_REGISTRY: ${{ secrets.HELM_REGISTRY || 'ghcr.io' }}
-      run: helm registry logout "${HELM_REGISTRY}" || true
-
-
     - name: Create GitHub Release
       uses: softprops/action-gh-release@v2
       if: startsWith(github.ref, 'refs/tags/')
@@ -136,3 +114,7 @@ jobs:
           bin/arctl-*
           build/charts/*.tgz
           build/charts/checksums.txt
+
+    - name: Log out of Helm registry
+      if: always()
+      run: helm registry logout "${HELM_REGISTRY}" || true

From 0c5c3b8d3d27ea73c652b662534d3afa9776410e Mon Sep 17 00:00:00 2001
From: Nik Matthiopoulos <nikolaos.matthiopoulos@solo.io>
Date: Thu, 12 Mar 2026 09:58:06 -0700
Subject: [PATCH 3/3] more cleanup

---
 .github/workflows/release.yml |  2 +-
 DEVELOPMENT.md                | 38 +++++++++++++++++++++++++++++++
 Makefile                      | 43 ++++++++---------------------------
 3 files changed, 49 insertions(+), 34 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7e2e51fb..de68bcb7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -103,7 +103,7 @@ jobs:
       run: make release-cli
 
     - name: Release Helm chart
-      run: make release-helm
+      run: make charts-release
 
     - name: Create GitHub Release
       uses: softprops/action-gh-release@v2
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index d8949fe6..1a9653ce 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -9,6 +9,7 @@ The fastest way to run the full stack locally is with [Kind](https://kind.sigs.k
 - [Docker](https://docs.docker.com/get-docker/)
 - [kubectl](https://kubernetes.io/docs/tasks/tools/)
 - [Helm](https://helm.sh/docs/intro/install/)
+- [envsubst](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html) (used to generate `Chart.yaml`)
 
 > `kind` is installed automatically into `./bin/kind` by `make install-tools` — no manual installation needed.
 
@@ -36,6 +37,8 @@ make install-agentregistry
 make install-agentregistry BUILD=false
 ```
 
+`install-agentregistry` automatically runs `charts-generate` first (see [Helm Chart Generation](#helm-chart-generation) below), so `Chart.yaml` is always up to date before deploying.
+
 On subsequent runs, `install-agentregistry` reuses the `jwtPrivateKey` already stored in the cluster secret so tokens remain valid across redeploys.
 
 ### Accessing the services
@@ -60,6 +63,41 @@ See [`scripts/kind/README.md`](scripts/kind/README.md) for more detail on config
 
 ---
 
+## Helm Chart Generation
+
+`charts/agentregistry/Chart.yaml` is **generated** from `charts/agentregistry/Chart-template.yaml` using `envsubst` and is not committed to the repository. Any `helm` command run directly against the chart directory will fail unless `Chart.yaml` exists.
+
+### Generating Chart.yaml locally
+
+```bash
+# Generate with version derived from the latest git tag (e.g. 0.3.0)
+make charts-generate
+
+# Generate with an explicit version
+make charts-generate CHART_VERSION=0.4.0
+```
+
+`CHART_VERSION` defaults to the output of `git describe --tags --abbrev=0` with the leading `v` stripped. If there are no tags, set it explicitly.
+
+Any Makefile target that needs `Chart.yaml` (e.g. `charts-lint`, `charts-test`, `charts-package`, `install-agentregistry`) declares `charts-generate` as a prerequisite and will generate it automatically. You only need to run `make charts-generate` directly if you're invoking `helm` commands by hand.
+
+### Adding Chart.yaml to your editor's ignore hints
+
+Because `charts/agentregistry/Chart.yaml` is gitignored, some editors may flag it as untracked. This is expected — treat `Chart-template.yaml` as the source of truth and do not commit the generated `Chart.yaml`.
+
+### Helm release pipeline
+
+The full release pipeline is encapsulated in a single target:
+
+```bash
+# Requires HELM_REGISTRY_PASSWORD to be set; optionally HELM_REGISTRY_USERNAME
+make charts-release CHART_VERSION=0.4.0
+```
+
+This runs in order: `charts-test` → `charts-push` (lint → package → push) → `charts-checksum`.
+
+---
+
 ## Local Docker Compose Environment
 
 ```bash
diff --git a/Makefile b/Makefile
index 9e1c7206..7e01ef47 100644
--- a/Makefile
+++ b/Makefile
@@ -420,18 +420,9 @@ charts-generate: ## Generate Chart.yaml from Chart-template.yaml (uses CHART_VER
 	  < $(HELM_CHART_DIR)/Chart-template.yaml \
 	  > $(HELM_CHART_DIR)/Chart.yaml
 
-# Package the chart, generating Chart.yaml from the template first.
-.PHONY: charts-package
-charts-package: charts-generate ## Generate Chart.yaml and package the Helm chart into $(HELM_PACKAGE_DIR)
-	@mkdir -p $(HELM_PACKAGE_DIR)
-	@echo "Packaging chart $(HELM_CHART_DIR) → $(HELM_PACKAGE_DIR)/"
-	$(HELM) package $(HELM_CHART_DIR) -d $(HELM_PACKAGE_DIR)
-	@echo "Packaged chart(s):"
-	@ls -1 $(HELM_PACKAGE_DIR)/*.tgz
-
 # Build chart dependencies (resolves Chart.yaml dependencies → charts/ subdir).
 .PHONY: charts-deps
-charts-deps: _helm-check ## Build Helm chart dependencies
+charts-deps: charts-generate _helm-check ## Build Helm chart dependencies
 	@echo "Building Helm chart dependencies for $(HELM_CHART_DIR)..."
 	$(HELM) dependency build $(HELM_CHART_DIR)
 
@@ -454,25 +445,20 @@ charts-render-test: charts-deps ## Render chart templates as a smoke test
 
 # Package the chart into $(HELM_PACKAGE_DIR)/.
 .PHONY: charts-package
-charts-package: charts-lint ## Package the Helm chart into $(HELM_PACKAGE_DIR)
+charts-package: charts-generate charts-lint ## Package the Helm chart into $(HELM_PACKAGE_DIR)
 	@mkdir -p $(HELM_PACKAGE_DIR)
 	@echo "Packaging chart $(HELM_CHART_DIR) → $(HELM_PACKAGE_DIR)/"
 	$(HELM) package $(HELM_CHART_DIR) -d $(HELM_PACKAGE_DIR)
 	@echo "Packaged chart(s):"
 	@ls -1 $(HELM_PACKAGE_DIR)/*.tgz
 
-# Internal: push pre-packaged chart. Does NOT login or package first.
-# Caller is responsible for authenticating with the registry before invoking this target.
-# Override registry/repo: make _helm-push HELM_REGISTRY=ghcr.io HELM_REPO=org/repo
-.PHONY: _helm-push
-_helm-push: _helm-check
+# Package the chart and push to an OCI registry. Caller must be logged in.
+# Override registry/repo: make charts-push HELM_REGISTRY=ghcr.io HELM_REPO=org/repo
+.PHONY: charts-push
+charts-push: charts-package _helm-check ## Package and push chart to the configured OCI registry
 	@echo "Pushing $(HELM_PACKAGE_DIR)/agentregistry-$(CHART_VERSION).tgz → oci://$(HELM_REGISTRY)/$(HELM_REPO)/charts"
 	$(HELM) push "$(HELM_PACKAGE_DIR)/agentregistry-$(CHART_VERSION).tgz" "oci://$(HELM_REGISTRY)/$(HELM_REPO)/charts"
 
-# Push packaged chart to an OCI registry (packages first). Caller must be logged in.
-.PHONY: charts-push
-charts-push: charts-package _helm-push ## Package and push chart to the configured registry
-
 # Generate SHA-256 checksums for all packaged chart files.
 .PHONY: charts-checksum
 charts-checksum: ## Generate SHA-256 checksum for the packaged chart in $(HELM_PACKAGE_DIR)
@@ -480,16 +466,11 @@ charts-checksum: ## Generate SHA-256 checksum for the packaged chart in $(HELM_P
 	@echo "--- checksum ---"
 	@cat $(HELM_PACKAGE_DIR)/checksums.txt
 
-# Full Helm release pipeline: generate Chart.yaml → lint → test → package → checksum → push.
+# Full Helm release pipeline: test → push (→ lint → package → generate + deps) → checksum.
 # Required env vars for the push step: HELM_REGISTRY_PASSWORD (and optionally HELM_REGISTRY_USERNAME).
-# Override version: make release-helm CHART_VERSION=1.2.3
-.PHONY: release-helm
-release-helm: ## Full Helm release: generate Chart.yaml, lint, test, package, checksum, and push
-	$(MAKE) charts-lint
-	$(MAKE) charts-test
-	$(MAKE) charts-package
-	$(MAKE) charts-checksum
-	$(MAKE) _helm-push
+# Override version: make charts-release CHART_VERSION=1.2.3
+.PHONY: charts-release
+charts-release: charts-test charts-push charts-checksum ## Full Helm release: lint, test, package, checksum, and push
 
 # Run helm-unittest against charts/agentregistry/tests/*.
 # This target:
@@ -520,7 +501,3 @@ helm-unittest-install: _helm-check ## Install the helm-unittest plugin if needed
 	  echo "helm-unittest plugin already installed"; \
 	fi
 
-# Convenience: package → push → test.
-.PHONY: charts-all
-charts-all: charts-push charts-test ## Package, push, and test the Helm chart
-	@echo "charts-all complete: packaged, pushed, and tested."