docs(helm): audit the chart documentation against the chart

Swept the remaining checkout-era references and audited the Helm docs by
checking every values path they mention against values.yaml rather than
reading them.

That found a real error: the chart has no `copilot.env`. The map is
`copilot.server.env`, so anyone following the env-validation note would have
set a key that silently does nothing. Fixed.

It also flagged `app.envDefaults.FREE_TABLES_LIMIT` and
`app.secrets.existingSecret.keys`, which are NOT bugs -- both appear only in
upgrade notes describing keys older releases shipped and this one removed.
Left exactly as they are; "fixing" them would delete the history an upgrader
needs.

The chart README was the bigger problem. It led with registry install after
the earlier commits, then used `./helm/sim` in eleven subsequent commands --
upgrade, dry-run, examples, parameters, secrets, troubleshooting. Someone
following the documented install had no such path. They now use the OCI
reference with a pinned version, with one note establishing that convention
so the checkout form does not have to be repeated everywhere.

Two related corrections while in there: the example values files are not part
of the packaged chart, so the examples section now fetches one at a release
tag instead of assuming it locally; and values.schema.json cannot be `cat`ed
without a checkout, so it links to the repo or `helm pull --untar`.

Left pointing at GitHub on purpose: the chart README deep links (that is
where the README lives, and an extra hop through the repository root would
be worse), the releases page, the issue tracker, the cosign identity regexp,
and the Docker Compose quick start's git clone.

Bumps to 1.9.4 per the chart's own gate.

Author: waleedlatif1

apps/docs/content/docs/platform/self-hosting/environment-variables.mdx

@@ -311,7 +311,7 @@ Setting the variable to an empty string does **not** remove it: the chart reads
 Null the variable in every layer that sets it. If it appears in both `app.env` and `app.envDefaults`, nulling only the `app.env` entry lets the `envDefaults` value apply again and the limit stays in force. With External Secrets, also drop the key from `externalSecrets.remoteRefs.app`, which keeps syncing it independently. Confirm what the pod will actually receive before rolling out:
 
 ```bash
-helm template sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.3 -f values.yaml | grep -A1 FREE_TABLE   # expect no output
+helm template sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 -f values.yaml | grep -A1 FREE_TABLE   # expect no output
 ```
 
 `null` deletion has no effect under `helm upgrade --reuse-values` — pass your full values with `-f`, or use `--reset-then-reuse-values` (Helm 3.14+). If you deploy with Argo CD, put the `null` in `valueFiles` or the `values` string rather than `valuesObject`, which strips nulls. On Docker Compose, delete the line from your `.env` file.

apps/docs/content/docs/platform/self-hosting/kubernetes.mdx

@@ -40,7 +40,7 @@ POSTGRES_PASSWORD=$(openssl rand -hex 24)
 
 # Install
 helm install sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.3 \
+  --version 1.9.4 \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
   --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
@@ -70,7 +70,7 @@ For clusters or GitOps configs that consume `helm repo add` rather than OCI:
 helm repo add sim https://charts.sim.ai
 helm repo update
 
-helm install sim sim/sim --version 1.9.3 --namespace simstudio --create-namespace \
+helm install sim sim/sim --version 1.9.4 --namespace simstudio --create-namespace \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
   --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
@@ -87,11 +87,11 @@ apply to the OCI artifact only.
 Every published version is signed with Sigstore keyless signing and carries a SLSA build-provenance attestation. Both live in the registry alongside the chart, so they survive a mirror into an internal registry.
 
 ```bash
-cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.3 \
+cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.4 \
   --certificate-identity-regexp '^https://github.com/simstudioai/sim/' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 
-gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.3 --repo simstudioai/sim
+gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.4 --repo simstudioai/sim
 ```
 
 Signing is Sigstore-only — there is no GPG `.prov` file, so `helm install --verify` does not apply.
@@ -112,7 +112,7 @@ SIM_RELEASE=v0.8.24
 curl -fsSLO "https://raw.githubusercontent.com/simstudioai/sim/$SIM_RELEASE/helm/sim/examples/values-aws.yaml"
 
 helm upgrade --install sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.3 \
+  --version 1.9.4 \
   --values values-aws.yaml \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
@@ -233,7 +233,7 @@ kubectl port-forward deployment/sim-app 3000:3000 -n simstudio
 kubectl logs -l app.kubernetes.io/component=app -n simstudio --tail=100
 
 # Upgrade (always pin the target chart version)
-helm upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.3 --namespace simstudio
+helm upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 --namespace simstudio
 
 # Uninstall
 helm uninstall sim --namespace simstudio

apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx

@@ -152,7 +152,7 @@ resource "helm_release" "sim" {
   # release with new migrations.
   repository = "oci://ghcr.io/simstudioai/charts"
   chart      = "sim"
-  version    = "1.9.3"
+  version    = "1.9.4"
 
   # Or the classic repository, if your tooling does not speak OCI:
   #   repository = "https://charts.sim.ai"

apps/docs/content/docs/platform/self-hosting/upgrades.mdx

@@ -157,15 +157,15 @@ Migration surprises are usually data-shaped rather than schema-shaped, so a stag
 
 ```bash
 helm upgrade sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.3 \
+  --version 1.9.4 \
   --namespace simstudio \
   --values my-values.yaml
 ```
 
 Preview first if the chart version changed:
 
 ```bash
-helm diff upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.3 -n simstudio --values my-values.yaml
+helm diff upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 -n simstudio --values my-values.yaml
 ```
 
 Then watch the rollout:

helm/sim/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 name: sim
 description: A Helm chart for Sim - the open-source AI workspace where teams build, deploy, and manage AI agents
 type: application
-version: 1.9.3
+version: 1.9.4
 appVersion: "v0.8.18"
 kubeVersion: ">=1.25.0-0"
 home: https://sim.ai

helm/sim/README.md

@@ -23,7 +23,7 @@ export POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')
 
 # Install from the registry
 helm install sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.3 \
+  --version 1.9.4 \
   --namespace sim --create-namespace \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
@@ -107,10 +107,10 @@ immutable once published.
 
 ```bash
 # List the published versions
-helm show chart oci://ghcr.io/simstudioai/charts/sim --version 1.9.3
+helm show chart oci://ghcr.io/simstudioai/charts/sim --version 1.9.4
 
 helm install sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.3 \
+  --version 1.9.4 \
   --namespace sim --create-namespace \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
@@ -127,8 +127,8 @@ To mirror the chart into an internal registry — the usual requirement for an
 air-gapped or internal-only cluster:
 
 ```bash
-helm pull oci://ghcr.io/simstudioai/charts/sim --version 1.9.3
-helm push sim-1.9.3.tgz oci://registry.internal.example.com/charts
+helm pull oci://ghcr.io/simstudioai/charts/sim --version 1.9.4
+helm push sim-1.9.4.tgz oci://registry.internal.example.com/charts
 ```
 
 The container images the chart references are listed in
@@ -144,7 +144,7 @@ helm repo add sim https://charts.sim.ai
 helm repo update
 
 helm install sim sim/sim \
-  --version 1.9.3 \
+  --version 1.9.4 \
   --namespace sim --create-namespace \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
@@ -169,20 +169,26 @@ helm install sim ./helm/sim \
   --set postgresql.auth.password="$POSTGRES_PASSWORD"
 ```
 
+The remaining examples in this README use the OCI reference. If you are working
+from a checkout, substitute `./helm/sim` and drop `--version` — the commands are
+otherwise identical.
+
 ### With a values file
 
 ```bash
-helm install sim ./helm/sim \
+helm install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.9.4 \
   --namespace sim --create-namespace \
   --values my-values.yaml
 ```
 
-Run `helm template ./helm/sim --values my-values.yaml | less` first to see what will be applied.
+Run `helm template oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 --values my-values.yaml | less` first to
+see what will be applied.
 
 ### Validate the install
 
 ```bash
-helm install sim ./helm/sim --dry-run --debug \
+helm install sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 --dry-run --debug \
   --values my-values.yaml \
   --set app.env.BETTER_AUTH_SECRET=$(openssl rand -hex 16) \
   --set app.env.ENCRYPTION_KEY=$(openssl rand -hex 16) \
@@ -201,12 +207,12 @@ the registry next to the chart so they survive a mirror.
 
 ```bash
 # The signature: proves this chart was signed by a GitHub Actions run in this repo
-cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.3 \
+cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.4 \
   --certificate-identity-regexp '^https://github.com/simstudioai/sim/' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 
 # The provenance: proves which workflow, commit, and runner produced it
-gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.3 --repo simstudioai/sim
+gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.4 --repo simstudioai/sim
 ```
 
 There is no GPG `.prov` file — signing is Sigstore-only, so there is no
@@ -218,7 +224,7 @@ GPG provenance format and will not work; use `cosign verify` above.
 ## Upgrading
 
 ```bash
-helm upgrade sim ./helm/sim --namespace sim --values my-values.yaml
+helm upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 --namespace sim --values my-values.yaml
 ```
 
 ---
@@ -248,7 +254,7 @@ kubectl delete namespace sim
 
 ## Examples
 
-Pre-built values files for common scenarios live in `helm/sim/examples/`. Each file has a header explaining when to use it and any prerequisites.
+Pre-built values files for common scenarios live in [`helm/sim/examples/`](https://github.com/simstudioai/sim/tree/main/helm/sim/examples). Each file has a header explaining when to use it and any prerequisites. They are **not** part of the packaged chart, so fetch the one you want at a release tag rather than expecting it locally.
 
 | File | When to use |
 |---|---|
@@ -266,9 +272,13 @@ Pre-built values files for common scenarios live in `helm/sim/examples/`. Each f
 Use one with:
 
 ```bash
-helm install sim ./helm/sim \
+SIM_RELEASE=v0.8.24
+curl -fsSLO "https://raw.githubusercontent.com/simstudioai/sim/$SIM_RELEASE/helm/sim/examples/values-production.yaml"
+
+helm install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.9.4 \
   --namespace sim --create-namespace \
-  --values ./helm/sim/examples/values-production.yaml \
+  --values values-production.yaml \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
   --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
@@ -283,12 +293,14 @@ This chart is intentionally configurable. Rather than maintain a hand-curated pa
 
 ```bash
 # Print all values with comments and defaults
-helm show values ./helm/sim
-
-# Print the JSON Schema (used by `helm install` to validate your values)
-cat ./helm/sim/values.schema.json
+helm show values oci://ghcr.io/simstudioai/charts/sim --version 1.9.4
 ```
 
+The JSON Schema that `helm install` validates your values against ships inside
+the chart as `values.schema.json`; read it in the
+[repository](https://github.com/simstudioai/sim/blob/main/helm/sim/values.schema.json)
+or extract it from a pulled chart with `helm pull --untar`.
+
 `values.yaml` is heavily commented; each top-level section explains what it controls and which sub-keys are required vs optional. For per-cloud examples and idiomatic overrides, see `examples/`.
 
 ---
@@ -329,7 +341,7 @@ Before installing in production, confirm each of the following:
             kubernetes.io/metadata.name: ingress-nginx
   ```
 * **Namespace hardening** — label the install namespace with Pod Security Standards `restricted` enforcement (`pod-security.kubernetes.io/enforce=restricted`). All workloads set `runAsNonRoot`, drop all Linux capabilities, disable privilege escalation, and set `seccompProfile: RuntimeDefault` — the four controls the Restricted profile requires. `readOnlyRootFilesystem` is intentionally **not** defaulted anywhere (Postgres/Ollama genuinely need a writable root; the stateless services — `realtime`, `pii`, `copilot` — could tolerate it but aren't pre-wired with a `/tmp` `emptyDir`). If your policy requires it, set `<component>.securityContext.readOnlyRootFilesystem: true` and mount an `emptyDir` at `/tmp` yourself via `extraVolumes`/`extraVolumeMounts`.
-* **Env validation** — keys under `app.env`, `realtime.env`, and `copilot.env` are passed through to the application and validated at startup. The JSON Schema intentionally does not enforce `additionalProperties: false` (would break custom user envs), so typos like `OPENA_API_KEY` (instead of `OPENAI_API_KEY`) surface as missing-key errors at runtime, not at `helm install` time. Review your env block carefully.
+* **Env validation** — keys under `app.env`, `realtime.env`, and `copilot.server.env` are passed through to the application and validated at startup. The JSON Schema intentionally does not enforce `additionalProperties: false` (would break custom user envs), so typos like `OPENA_API_KEY` (instead of `OPENAI_API_KEY`) surface as missing-key errors at runtime, not at `helm install` time. Review your env block carefully.
 * **Set public URLs** — `app.env.NEXT_PUBLIC_APP_URL` and `app.env.BETTER_AUTH_URL` must match your public origin (e.g. `https://sim.example.com`). Leaving them as `localhost` breaks sign-in.
 
 ---
@@ -341,7 +353,7 @@ The chart supports three ways to provide secrets, in increasing order of product
 ### 1. Inline `--set` (dev / dry-run only)
 
 ```bash
-helm install sim ./helm/sim --set app.env.BETTER_AUTH_SECRET=...
+helm install sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 --set app.env.BETTER_AUTH_SECRET=...
 ```
 
 Discouraged for production — values land in `helm get values` output.
@@ -472,7 +484,7 @@ With the chart-managed Secret (the default), nulling a key the application canno
 The common case is a free-tier cap inherited from a chart release older than the one that stopped presetting them, which shipped `FREE_TABLES_LIMIT: "3"` and `FREE_TABLE_ROWS_LIMIT: "1000"` under `app.envDefaults`. With billing disabled, Sim reads an unset limit as unlimited, so nulling these lifts the cap. Verify before rolling out:
 
 ```bash
-helm template sim ./helm/sim -f values.yaml | grep -A1 FREE_TABLE   # expect no output
+helm template sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 -f values.yaml | grep -A1 FREE_TABLE   # expect no output
 ```
 
 ---
@@ -540,7 +552,7 @@ Without a cluster-reachable `INTERNAL_API_BASE_URL` (it falls back to `NEXT_PUBL
 You ran `helm install` without setting required secrets. Generate them and pass with `--set`:
 
 ```bash
-helm install sim ./helm/sim \
+helm install sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.4 \
   --set app.env.BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
   --set app.env.ENCRYPTION_KEY=$(openssl rand -hex 32) \
   --set app.env.INTERNAL_API_SECRET=$(openssl rand -hex 32) \