Chore: Set up helmcov and helmdocs for charts.

.githooks/pre-commit

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+staged="$(git diff --cached --name-only --diff-filter=ACMR || true)"
+
+if [[ -z "${staged}" ]]; then
+  exit 0
+fi
+
+chart_changes=false
+docs_changes=false
+
+while IFS= read -r path; do
+  [[ -z "${path}" ]] && continue
+  case "${path}" in
+    charts/*)
+      chart_changes=true
+      case "${path}" in
+        charts/*/Chart.yaml|charts/*/values.yaml|charts/*/README.md.gotmpl|charts/*/templates/*|scripts/helmdocs.sh|scripts/install-helm-docs.sh)
+          docs_changes=true
+          ;;
+      esac
+      ;;
+  esac
+done <<< "${staged}"
+
+if [[ "${chart_changes}" == true ]]; then
+  make test
+fi
+
+if [[ "${docs_changes}" == true ]]; then
+  make docs
+  if ! git diff --quiet -- charts/clickstack/README.md charts/clickstack-operators/README.md; then
+    echo "Chart README(s) are out of date. Run 'make docs' and stage the updated README.md files." >&2
+    exit 1
+  fi
+fi

.github/workflows/helm-test.yaml

@@ -5,45 +5,34 @@ on:
     branches: [ main ]
     paths:
       - 'charts/**'
+      - 'examples/**'
+      - 'Makefile'
+      - 'scripts/**'
+      - '.githooks/**'
+      - '.github/workflows/helm-test.yaml'
   pull_request:
     branches: [ main ]
+    paths:
+      - 'charts/**'
+      - 'examples/**'
+      - 'Makefile'
+      - 'scripts/**'
+      - '.githooks/**'
+      - '.github/workflows/helm-test.yaml'
 
 jobs:
   helm-unittest:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y unzip git curl
+        uses: actions/checkout@v4
 
       - name: Set up Helm
-        uses: azure/setup-helm@v3
+        uses: azure/setup-helm@v4
         with:
           version: v3.12.0
 
-      - name: Install helm-unittest plugin
-        run: |
-          helm plugin install https://github.com/helm-unittest/helm-unittest.git --version v1.0.3 ${{ runner.debug && '--debug' || ''}}
-
-      - name: Build chart dependencies
-        run: |
-          helm repo add mongodb https://mongodb.github.io/helm-charts
-          helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
-          helm dependency build charts/clickstack
-
-      - name: Validate example values render
-        run: |
-          helm template clickstack-example charts/clickstack \
-            -f examples/alb-ingress/values.yaml >/dev/null
-          helm template clickstack-example charts/clickstack \
-            -f examples/api-only/values.yaml >/dev/null
-
-      - name: Run helm-unittest
-        run: |
-          helm unittest charts/clickstack
+      - name: Run unit tests and verify docs
+        run: make setup test docs
+      - name: Check generated chart READMEs are committed
+        run: git diff --exit-code -- charts/clickstack/README.md charts/clickstack-operators/README.md

.github/workflows/helmcov.yaml

@@ -0,0 +1,44 @@
+name: Helm Template Coverage
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'charts/**'
+      - 'Makefile'
+      - 'scripts/**'
+      - '.github/workflows/helmcov.yaml'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'charts/**'
+      - 'Makefile'
+      - 'scripts/**'
+      - '.github/workflows/helmcov.yaml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  helmcov:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: v3.12.0
+
+      - name: Build chart dependencies
+        run: make chart-deps
+
+      - name: Run helmcov
+        uses: jordan-simonovski/helmcov@v1
+        with:
+          chart: charts/clickstack
+          tests: charts/clickstack/tests
+          threshold: "30"
+          version: v0.4.0

.gitignore

@@ -13,3 +13,11 @@ node_modules
 !.yarn/versions
 
 charts/*/charts/*.tgz
+
+# helmcov
+coverage.out
+coverage.xml
+
+# local tooling
+.tools/
+.helmcov-work/

AGENTS.md

@@ -8,6 +8,21 @@ Helm charts for ClickStack (HyperDX observability platform). Two charts:
 
 Package manager: Yarn 4 (via Corepack). Versioning: Changesets.
 
+## Local Development
+
+Use the Makefile for tool setup, unit tests, and template coverage:
+
+```bash
+make setup      # install helm-unittest, chart deps, and git hooks
+make test       # helm-unittest + example values validation
+make coverage   # helmcov template coverage via Docker (requires Docker)
+make ci         # test + coverage
+```
+
+The pre-commit hook runs `make test` when staged files under `charts/` change, and
+`make docs` when chart values, templates, or README templates change. Install hooks
+with `make setup` or `make hooks`.
+
 ## Build & Dependency Commands
 
 ```bash
@@ -35,14 +50,8 @@ helm template clickstack-test charts/clickstack -f examples/api-only/values.yaml
 
 ### Unit Tests (helm-unittest)
 
-Requires the `helm-unittest` plugin:
-```bash
-helm plugin install https://github.com/helm-unittest/helm-unittest.git --version v1.0.3
-```
-
 ```bash
-# Run ALL unit tests
-helm unittest charts/clickstack
+make test
 
 # Run a SINGLE test file
 helm unittest -f tests/app-deployment_test.yaml charts/clickstack
@@ -54,6 +63,61 @@ helm unittest -f 'tests/clickhouse-*_test.yaml' charts/clickstack
 Test files live in `charts/clickstack/tests/` and follow the naming convention
 `<component>_test.yaml`. Snapshots are stored in `tests/__snapshot__/`.
 
+Shared value fixtures live in `charts/clickstack/tests/values/<case>.yaml` and are
+loaded with the suite-level `values:` key when a test needs more data than inline
+`set:` overrides comfortably provide:
+
+```yaml
+suite: Test Deployment Default Sources Tpl
+templates:
+  - hyperdx/deployment.yaml
+values:
+  - values/deployment-tpl-defaults.yaml
+tests:
+  - it: should render tpl-interpolated default connections
+    asserts:
+      - matchRegex:
+          path: spec.template.spec.containers[0].env[?(@.name=="DEFAULT_CONNECTIONS")].value
+          pattern: clickhouse-headless
+```
+
+Prefer inline `set:` for small overrides; use `tests/values/` for multi-field
+fixtures or tpl-heavy defaults reused across assertions.
+
+### Template Coverage (helmcov)
+
+```bash
+make coverage
+
+# Verbose per-file output
+VERBOSE=1 make coverage
+
+# Gate on minimum line coverage once baseline is known
+COVERAGE_THRESHOLD=30 make coverage
+
+# Override the pinned image (see scripts/tool-versions.env)
+HELMCOV_IMAGE=ghcr.io/example/helmcov@sha256:... make coverage
+```
+
+Uses the digest-pinned image in `scripts/tool-versions.env` with a **30% line
+coverage threshold** for local runs. Outputs `coverage.out` (Go coverprofile) and
+`coverage.xml` (Cobertura).
+
+CI runs the [helmcov GitHub Action](https://github.com/jordan-simonovski/helmcov)
+via `.github/workflows/helmcov.yaml`, which posts or updates a pull request
+comment with line/branch coverage and uncovered details.
+
+### Chart README (helm-docs)
+
+```bash
+make docs
+```
+
+Regenerates `charts/*/README.md` from `values.yaml` using [helm-docs](https://github.com/norwoodj/helm-docs).
+Only values with `#` comments in `values.yaml` appear in the README (`--ignore-non-descriptions`).
+Each chart README includes version and CI build status badges.
+The pre-commit hook verifies docs are up to date when values or templates change.
+
 ### Integration Tests (Kind cluster)
 
 Suites live under `integration-tests/<suite-name>/`. Each has `suite.yaml`,
@@ -103,6 +167,8 @@ Requires: `kind`, `helm`, `kubectl`, `yq`.
 
 ### Values Structure (`values.yaml`)
 - Top-level keys: `global`, `hyperdx`, `clickhouse`, `mongodb`, `otel-collector`
+- Document user-facing values with `# --` comments directly above each key (helm-docs format)
+- `make docs` omits undocumented keys (`--ignore-non-descriptions`); prefer commenting parent keys for operator/subchart passthrough specs
 - `hyperdx.config` — non-sensitive env vars (ConfigMap), supports `tpl` expressions
 - `hyperdx.secrets` — sensitive env vars (Secret); set to `null` to skip creation
 - `hyperdx.deployment` — Deployment spec (image, replicas, resources, probes, etc.)
@@ -151,6 +217,7 @@ tests:
 | Workflow | File | Trigger | Purpose |
 |----------|------|---------|---------|
 | Helm Chart Tests | `helm-test.yaml` | push/PR to main | Unit tests + example validation |
+| Helm Template Coverage | `helmcov.yaml` | push/PR to main | helmcov action; PR comment with line/branch coverage |
 | Integration Test | `chart-test.yml` | push/PR/nightly | Kind-based integration suites |
 | Release | `release.yml` | after tests pass on main | Changeset version + chart release |
 | Update App Version | `update-app-version.yml` | workflow_dispatch | Bump `appVersion` in Chart.yaml |
@@ -165,3 +232,4 @@ tests:
 - Example values: `examples/*/values.yaml`
 - Version sync script: `scripts/update-chart-versions.js`
 - Smoke test: `scripts/smoke-test.sh`
+- Makefile: `make setup`, `make test`, `make coverage`

Makefile

@@ -0,0 +1,65 @@
+SHELL := /bin/bash
+
+include scripts/tool-versions.env
+export HELM_DOCS_VERSION HELMCOV_IMAGE
+
+CHART ?= charts/clickstack
+HELM_UNITTEST_VERSION ?= v1.0.3
+HELM_UNITTEST_PLUGIN := https://github.com/helm-unittest/helm-unittest.git
+COVERAGE_THRESHOLD ?= 30
+
+.PHONY: help setup hooks chart-deps install-helm-unittest install-helm-docs validate test coverage docs ci
+
+help:
+	@echo "Targets:"
+	@echo "  make setup     Install helm-unittest, helm-docs, chart deps, and git hooks"
+	@echo "  make test      Run helm-unittest and example values validation"
+	@echo "  make coverage  Run helmcov template coverage via Docker (min $(COVERAGE_THRESHOLD)%)"
+	@echo "  make docs      Regenerate chart README files from values.yaml via helm-docs"
+	@echo "  make ci        Run test, coverage, and docs verification"
+	@echo ""
+	@echo "Variables:"
+	@echo "  CHART=$(CHART)"
+	@echo "  HELMCOV_IMAGE=$(HELMCOV_IMAGE)"
+	@echo "  HELM_UNITTEST_VERSION=$(HELM_UNITTEST_VERSION)"
+	@echo "  COVERAGE_THRESHOLD=$(COVERAGE_THRESHOLD)"
+
+setup: hooks install-helm-unittest install-helm-docs chart-deps
+	@echo "Setup complete."
+
+hooks:
+	./scripts/install-hooks.sh
+
+install-helm-docs:
+	./scripts/install-helm-docs.sh
+
+chart-deps:
+	@command -v helm >/dev/null || { echo "helm is required; install Helm 3 first." >&2; exit 1; }
+	helm repo add mongodb https://mongodb.github.io/helm-charts >/dev/null 2>&1 || true
+	helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts >/dev/null 2>&1 || true
+	helm dependency build $(CHART)
+
+install-helm-unittest:
+	@command -v helm >/dev/null || { echo "helm is required; install Helm 3 first." >&2; exit 1; }
+	@if helm plugin list 2>/dev/null | awk '{print $$1}' | grep -qx unittest; then \
+		echo "helm-unittest already installed"; \
+	else \
+		echo "Installing helm-unittest $(HELM_UNITTEST_VERSION)..."; \
+		helm plugin install $(HELM_UNITTEST_PLUGIN) --version $(HELM_UNITTEST_VERSION); \
+	fi
+
+validate: chart-deps
+	helm template clickstack-example $(CHART) -f examples/alb-ingress/values.yaml >/dev/null
+	helm template clickstack-example $(CHART) -f examples/api-only/values.yaml >/dev/null
+
+test: chart-deps validate
+	helm unittest $(CHART)
+
+coverage: chart-deps
+	THRESHOLD=$(COVERAGE_THRESHOLD) HELMCOV_IMAGE=$(HELMCOV_IMAGE) ./scripts/helmcov.sh
+
+docs: install-helm-docs
+	./scripts/helmdocs.sh
+
+ci: test coverage docs
+	@git diff --exit-code -- charts/clickstack/README.md charts/clickstack-operators/README.md

README.md

@@ -18,8 +18,8 @@ For configuration, cloud deployment, ingress setup, and troubleshooting, see the
 
 ## Charts
 
-- **`clickstack/clickstack-operators`** - Installs the MongoDB and ClickHouse operator controllers and CRDs. Must be installed first.
-- **`clickstack/clickstack`** - Installs HyperDX, OpenTelemetry Collector, and operator custom resources.
+- **[`clickstack/clickstack-operators`](charts/clickstack-operators/README.md)** - Installs the MongoDB and ClickHouse operator controllers and CRDs. Must be installed first.
+- **[`clickstack/clickstack`](charts/clickstack/README.md)** - Installs HyperDX, OpenTelemetry Collector, and operator custom resources.
 
 ## Additional Manifests
 

charts/clickstack-operators/.helmignore

@@ -0,0 +1,2 @@
+# helm-docs source template (README.md is the published doc)
+README.md.gotmpl