docs: merge helm.md into charts/README.md as the canonical helm guide

charts/README.md was a contributor-oriented design doc; docs/deployment/helm.md
was a thin deploy walkthrough that linked back to it. Collapse to one entry
point — charts/README.md leads with install/upgrade commands, then layout,
prerequisites, design decisions. Update the three call sites (root README
twice, docker.md "going to production").

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cosmic-flood

README.md

@@ -37,16 +37,6 @@ The fastest path is the hosted version: sign up at **[featbit.co](https://featbi
 
 #### 2. Self-host with Docker Compose
 
-```bash
-cd modules
-cp .env.example .env       # defaults are fine for first boot
-docker compose up -d       # pulls images, brings up everything, applies schemas
-```
-
-Open [http://localhost:3000](http://localhost:3000) and log in with your FeatBit account.
-
-The compose stack brings up web, track-service, PostgreSQL, and ClickHouse together. ClickHouse's schema is auto-applied via `/docker-entrypoint-initdb.d/`; the web container runs `prisma migrate deploy` on every start. Override `DATABASE_URL` / `CLICKHOUSE_CONNECTION_STRING` in `.env` to use external databases instead of the bundled ones.
-
 Full step-by-step guide: **[`docs/deployment/docker.md`](docs/deployment/docker.md)**.
 
 #### 3. Self-host with Helm on Kubernetes
@@ -59,7 +49,7 @@ helm install featbit-rda charts/featbit-rda \
   -f charts/featbit-rda/examples/aks/values.yaml
 ```
 
-Full guide and AKS reference values: **[`docs/deployment/helm.md`](docs/deployment/helm.md)**.
+Full guide and AKS reference values: **[`charts/README.md`](charts/README.md)**.
 
 ### Usage
 
@@ -129,9 +119,8 @@ Every experiment carries a `dataSourceMode`. The default (`featbit-managed`) pul
 - **[`AGENTS.md`](AGENTS.md)** — full service map, environment variables, troubleshooting, and the canonical metric storage contract.
 - **[`WHITE_PAPER.md`](WHITE_PAPER.md)** — product thesis and market positioning.
 - **[`docs/deployment/docker.md`](docs/deployment/docker.md)** — Docker Compose deployment, end to end.
-- **[`docs/deployment/helm.md`](docs/deployment/helm.md)** — Helm chart deployment.
+- **[`charts/README.md`](charts/README.md)** — Helm chart deployment: install, prerequisites, layout, design decisions, AKS examples.
 - **[`docs/usage/`](docs/usage/)** — usage docs (placeholder until the docs site is published).
-- **[`charts/README.md`](charts/README.md)** — Helm chart layout, design decisions, AKS examples.
 - **[`skills/featbit-release-decision/`](skills/featbit-release-decision/)** — the release-decision workflow + CF-01 → CF-08 phase definitions.
 - **[`modules/experimentation-claude-code-connector/README.md`](modules/experimentation-claude-code-connector/README.md)** — Local-mode bridge: install, config, SSE contract, publishing.
 - **[`tutorial/`](tutorial/)** — Bayesian and experimentation learning notes (EN / 中文).

charts/README.md

@@ -1,6 +1,45 @@
-# charts/
+# FeatBit RDA Helm chart
 
-Helm charts for deploying the FeatBit Release Decision Agent (modules/*) to Kubernetes.
+Helm chart for deploying FeatBit Release Decision Agent (`modules/*`) to Kubernetes — production-grade install with autoscaling, ingress + TLS, and secret projection from Key Vault.
+
+The chart is deliberately cloud-neutral. It does **not** provision PostgreSQL or ClickHouse, and it does **not** apply any DDL.
+
+---
+
+## Install
+
+```bash
+helm install featbit-rda charts/featbit-rda \
+  --namespace featbit --create-namespace \
+  -f charts/featbit-rda/examples/aks/values.yaml
+```
+
+A reference AKS install (NGINX ingress, cert-manager, Key Vault CSI) is documented in [`featbit-rda/examples/aks/`](featbit-rda/examples/aks/). A Docker Desktop smoke-test profile lives in [`featbit-rda/examples/local/`](featbit-rda/examples/local/).
+
+## Upgrade
+
+```bash
+helm upgrade featbit-rda charts/featbit-rda \
+  -n featbit -f path/to/your/values.yaml
+```
+
+---
+
+## Prerequisites you MUST provision before `helm install`
+
+A few things must exist *before* you run `helm install`, or pods will fail to start:
+
+1. **PostgreSQL database** reachable from the cluster (used by the `web` service). The role in the connection string needs `CREATE` / `ALTER` privileges — `web` runs `prisma migrate deploy` on every start.
+
+2. **ClickHouse database and tables** *(only if you keep `track-service`)*. The chart writes to `<database>.flag_evaluations` and `<database>.metric_events`. `<database>` is controlled by `trackService.clickHouse.database` in your values — make it match the DB on your CH where those tables already exist. Reference schema: [`../modules/track-service/sql/schema.sql`](../modules/track-service/sql/schema.sql).
+
+3. **A Kubernetes Secret holding the ClickHouse connection string.** The chart consumes this via `trackService.clickHouse.existingSecret`. For AKS this is typically **projected from Azure Key Vault** by applying a `SecretProviderClass` manifest (see [`featbit-rda/examples/aks/keyvault-secret-provider.yaml`](featbit-rda/examples/aks/keyvault-secret-provider.yaml)) **before** installing the chart. The SPC is intentionally *not* part of this chart — SPC is Azure-specific infrastructure plumbing, the chart is the application. For dev you can skip the SPC and just set `trackService.clickHouse.connectionString` directly; the chart will generate the Secret itself.
+
+4. **Container images pushed to a registry the kubelet can reach.** On AKS: `az aks update --attach-acr <acr>` once per cluster removes the need for `imagePullSecrets`.
+
+5. *(optional)* **Ingress controller + cert-manager `ClusterIssuer`** — only needed if `trackService.ingress.enabled: true` (or any other `*.ingress.enabled`).
+
+---
 
 ## Layout
 
@@ -25,58 +64,21 @@ charts/
             └── values.yaml
 ```
 
-The chart never provisions ClickHouse or applies DDL — the target DB and
-tables (see `modules/track-service/sql/schema.sql` for the reference schema)
-are assumed to exist.
-
-## Prerequisites you MUST provision before `helm install`
-
-The chart deliberately stays cloud-neutral. A few things must exist *before*
-you run `helm install`, or pods will fail to start:
-
-1. **ClickHouse DB and tables.** The chart writes to `<database>.flag_evaluations`
-   and `<database>.metric_events`. `<database>` is controlled by
-   `trackService.clickHouse.database` in your values — make it match the DB
-   on your CH where those tables already exist.
-
-2. **A Kubernetes Secret holding the ClickHouse connection string.**
-   The chart consumes this via `trackService.clickHouse.existingSecret`.
-   For AKS this is typically **projected from Azure Key Vault** by applying
-   a `SecretProviderClass` manifest (see `featbit-rda/examples/aks/keyvault-secret-provider.yaml`)
-   **before** installing the chart. The SPC is intentionally *not* part of
-   this chart — SPC is Azure-specific infrastructure plumbing, the chart
-   is the application. For dev you can skip the SPC and just set
-   `trackService.clickHouse.connectionString` directly; the chart will
-   generate the Secret itself.
-
-3. **Image pulled from a registry the AKS kubelet can reach.** For AKS:
-   `az aks update --attach-acr <acr>` once per cluster.
-
-4. **Ingress controller + (optional) cert-manager ClusterIssuer.** Only
-   needed if `trackService.ingress.enabled: true`.
-
 ## Design decisions
 
-- **Umbrella chart, not per-service charts.** One `helm install` deploys
-  everything; each service is toggled via `<service>.enabled`. This matches
-  the pattern used in [featbit-charts](https://github.com/featbit/featbit-charts).
-- **NGINX Ingress, not one LoadBalancer per service.** Single public IP,
-  routing by `Host:`, free TLS via cert-manager + Let's Encrypt.
-- **Image registry = Azure Container Registry.** AKS is attached to the ACR
-  via `az aks update --attach-acr`, so no `imagePullSecrets` are required.
-- **Secrets.** Dev/staging path: put plain values in `values.local.yaml` and
-  the chart generates a Secret. Production path: project secrets from Azure
-  Key Vault via the CSI driver; the chart just reads the Secret the driver
-  creates.
+- **Umbrella chart, not per-service charts.** One `helm install` deploys everything; each service is toggled via `<service>.enabled`. This matches the pattern used in [featbit-charts](https://github.com/featbit/featbit-charts).
+- **NGINX Ingress, not one LoadBalancer per service.** Single public IP, routing by `Host:`, free TLS via cert-manager + Let's Encrypt.
+- **Image registry = Azure Container Registry.** AKS is attached to the ACR via `az aks update --attach-acr`, so no `imagePullSecrets` are required.
+- **Secrets.** Dev/staging path: put plain values in `values.local.yaml` and the chart generates a Secret. Production path: project secrets from Azure Key Vault via the CSI driver; the chart just reads the Secret the driver creates.
 
 ## Adding a new service
 
 1. Add a section to `charts/featbit-rda/values.yaml` (e.g. `statsService:`).
-2. Add `charts/featbit-rda/templates/stats-service-{deployment,service,ingress,hpa,pdb,serviceaccount}.yaml`,
-   all gated on `.Values.statsService.enabled`.
+2. Add `charts/featbit-rda/templates/stats-service-{deployment,service,ingress,hpa,pdb,serviceaccount}.yaml`, all gated on `.Values.statsService.enabled`.
 3. Add helpers (`statsService.fullname`, `statsService.image`, …) to `_helpers.tpl`.
 4. Extend `examples/aks/values.yaml` with the new service's overrides.
 
-## Quick start
+## Further reading
 
-See [`featbit-rda/examples/aks/README.md`](featbit-rda/examples/aks/README.md).
+- [`featbit-rda/examples/aks/README.md`](featbit-rda/examples/aks/README.md) — end-to-end AKS install with ACR, Key Vault, ingress, and TLS.
+- [`../AGENTS.md`](../AGENTS.md) — service map, env vars, metric storage contract.

docs/deployment/docker.md

@@ -103,7 +103,7 @@ docker compose up -d web postgres
 
 ## Going to production
 
-Compose is fine for a single host. For HA, autoscaling, ingress + TLS, secret projection from Key Vault, and pod disruption budgets, use the Helm chart instead — see [`helm.md`](helm.md).
+Compose is fine for a single host. For HA, autoscaling, ingress + TLS, secret projection from Key Vault, and pod disruption budgets, use the Helm chart instead — see [`charts/README.md`](../../charts/README.md).
 
 ---