camunda · bkenez · Jun 26, 2026 · Jun 26, 2026
@@ -98,6 +98,8 @@ Each chart version depends on: Bitnami Keycloak (local sub-chart), Bitnami Postg
 
 ## Conventions
 
+Path-scoped chart-coding conventions live in `.github/instructions/*.instructions.md` (values.yaml authoring, Helm templates, code review, Go tests, scripting, GitHub Actions). Their `applyTo:` globs are not auto-applied by Claude Code — read the matching guide explicitly before editing files in that path.
+
 ### Commits and PRs
 
 Commit messages and PR titles use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) format:

@@ -52,6 +52,7 @@ Do not introduce templates that:
 - **NEVER** change a helper name that is already exported without updating all callers across all chart versions.
 - **NEVER** use `range` over `extraConfiguration` without the `kindIs "slice"` branch — it supports both map and slice forms.
 - **NEVER** inline multi-line YAML strings without `indent N | trim` to prevent YAML parse errors.
+- **NEVER** write a render-time warning directly into `NOTES.txt`. Declare it inside the `camunda.constraints.warnings` define in the constraints template (`templates/common/constraints.tpl` on 8.8+; `templates/camunda/constraints.tpl` on 8.7 and older); `NOTES.txt` surfaces warnings only via `{{ include "camunda.constraints.warnings" . | trim }}`.
 
 ### ALWAYS
 - **ALWAYS** use `{{-` / `-}}` to strip whitespace around block-level directives.
@@ -61,6 +62,7 @@ Do not introduce templates that:
 - **ALWAYS** use `tpl` when rendering user-supplied label/annotation maps to support template expressions.
 - **ALWAYS** use `camundaPlatform.imageByParams` to resolve images — never concatenate `image:tag` manually.
 - **ALWAYS** keep 2-space YAML indentation throughout.
+- **ALWAYS** raise hard validation failures at the top level of the constraints template and abort with `fail` (piped `... | fail` or a direct `fail (...)` call); raise non-fatal warnings inside the `camunda.constraints.warnings` define (no `fail`). Prefer the `[camunda][error]` / `[camunda][warning]` message prefixes — they are the house convention used by nearly all existing entries.
 
 ---
 
@@ -201,6 +203,41 @@ volumeMounts:
   ) | nindent 10 }}
 ```
 
+### 10. Render-Time Constraints and Warnings
+
+All render-time validation lives in the constraints template — `templates/common/constraints.tpl`
+on 8.8+, `templates/camunda/constraints.tpl` on 8.7 and older — in two distinct shapes.
+`NOTES.txt` does NOT author warnings — it only includes them: `{{ include "camunda.constraints.warnings" . | trim }}`.
+
+**Hard failure** — top-level (outside any `define`), aborts the render with `fail` (the piped form
+below, or an equivalent direct `fail (printf "[camunda][error] ...")` call):
+
+```yaml
+{{- if and .Values.foo.enabled (not .Values.foo.secret.existingSecret) }}
+  {{- $errorMessage := printf "[camunda][error] %s"
+      "foo.enabled requires foo.secret.existingSecret to be set."
+  -}}
+  {{ printf "\n%s" $errorMessage | trimSuffix "\n" | fail }}
+{{- end }}
+```
+
+**Soft warning** — inside the `camunda.constraints.warnings` define, returns a string, **no `fail`**:
+
+```yaml
+{{- define "camunda.constraints.warnings" }}
+  {{- if .Values.console.enabled }}
+    {{- $warningMessage := printf "%s %s"
+        "[camunda][warning]"
+        "DEPRECATION: \"console.enabled\" is deprecated; use \"camundaHub.enabled: true\" instead."
+    -}}
+    {{ printf "\n%s" $warningMessage | trimSuffix "\n" }}
+  {{- end }}
+{{- end }}
+```
+
+For deprecated values keys, prefer the `camundaPlatform.keyDeprecated` helper (non-fatal) over
+hand-rolling the warning; it must be called from within `camunda.constraints.warnings`.
+
 ---
 
 ## Common Mistakes
@@ -228,6 +265,10 @@ volumeMounts:
 
 8. **Missing `enabled` guard** — resources emitted when a component is disabled cause Helm install failures.
 
+9. **Writing a warning into `NOTES.txt`** — install/upgrade warnings belong in the
+   `camunda.constraints.warnings` define in `constraints.tpl`, not as hand-written prose in
+   `NOTES.txt`. `NOTES.txt` only renders them via the `include` (see Pattern 10).
+
 ---
 
 ## Resources
@@ -236,6 +277,7 @@ volumeMounts:
 - Chart design principles: `docs/index.md`
 - `common/_helpers.tpl`: `charts/<version>/templates/common/_helpers.tpl`
 - `common/_utilz.tpl`: `charts/<version>/templates/common/_utilz.tpl`
+- Constraints & warnings: `charts/<version>/templates/common/constraints.tpl` (8.8+) or `charts/<version>/templates/camunda/constraints.tpl` (8.7 and older)
 - Version differences overview: `AGENTS.md` (Version-Aware Rules section)
 - Render templates locally: `make helm.template chartPath=charts/camunda-platform-8.10`
 - Lint: `make helm.lint chartPath=charts/camunda-platform-8.10`
@@ -139,17 +139,52 @@ image:
   pullSecrets: []
 ```
 
-### 6. Optional Secret Pattern
+### 6. Secret Block Pattern
+
+Secrets use the **canonical `secret:` map** — reuse it verbatim; do **not** invent a new secret
+layout. ADR-0068 standardizes the `existingSecret` interface across all components, and the
+constraints template validates inputs against it — drift here reintroduces exactly the
+inconsistency that standardization removed. The full shape is `inlineSecret` → `existingSecret` →
+`existingSecretKey`; certificate / CA references use the `existingSecret` / `existingSecretKey`
+subset (no inline form).
+
+Canonical block — real example `identity.externalDatabase.secret`, shown with its parent nesting:
 
 ```yaml
-## @extra orchestration.auth.existingSecret can be used to reference an existing Kubernetes Secret.
-auth:
-  ## @param orchestration.auth.existingSecret can be used to reference an existing Secret containing auth credentials.
-  existingSecret: ""
-  ## @param orchestration.auth.existingSecretKey defines the key within the existing secret.
-  existingSecretKey: ""
-  ## @param orchestration.auth.inlineSecret can be used to provide the auth secret inline (non-production only).
-  inlineSecret: ""
+identity:
+  externalDatabase:
+    ## @extra identity.externalDatabase.secret configuration to provide the external database password secret.
+    secret:
+      ## @param identity.externalDatabase.secret.inlineSecret can be used to provide the password as a plain-text value for non-production usage.
+      inlineSecret: ""
+      ## @param identity.externalDatabase.secret.existingSecret can be used to reference an existing Kubernetes Secret containing the password.
+      existingSecret: ""
+      ## @param identity.externalDatabase.secret.existingSecretKey defines the key within the existing secret object.
+      existingSecretKey: ""
+```
+
+- **Key order is fixed:** `inlineSecret` → `existingSecret` → `existingSecretKey` (matches
+  `global.license.secret` and `global.documentStore.type.aws.*.secret` in `values.yaml`).
+- **Multiple secret values** (e.g. an access key ID *and* a secret access key) → one named entry
+  per value, each wrapping its **own** canonical `secret:` block. Reference:
+  `global.documentStore.type.aws.{accessKeyId,secretAccessKey}.secret` in `values.yaml`.
+- **Auxiliary (non-secret) config goes BESIDE the `secret:` block, never inside it.** Only the
+  secret-source keys belong in `secret:`; a key alias, a keystore/cert `type` selector, a
+  `proxyVerify` or `autoRollout` toggle, etc. are SIBLINGS of `secret:`. Real precedent —
+  `global.tls.caBundle`, where `autoRollout` (and `image`) sit beside `secret:`:
+
+```yaml
+global:
+  tls:
+    caBundle:
+      ## @extra global.tls.caBundle.secret configuration to provide the CA bundle secret.
+      secret:
+        ## @param global.tls.caBundle.secret.existingSecret can be used to reference an existing Kubernetes Secret containing the PEM-encoded CA bundle.
+        existingSecret: ""
+        ## @param global.tls.caBundle.secret.existingSecretKey defines the key within the existing secret object.
+        existingSecretKey: "ca.crt"
+      ## @param global.tls.caBundle.autoRollout if true, rolls Java components when the CA Secret changes.
+      autoRollout: false
 ```
 
 ### 7. Component Structure Pattern
@@ -278,6 +313,11 @@ using the layer availability table in `docs/skills/integration-test-scenario-res
     by default, verify all identity/persistence/feature layer files don't conflict. Consult
     `docs/skills/integration-test-scenario-resolution.md` to understand which layer files exist per version.
 
+11. **Non-standard secret block** — inventing a new secret layout, reordering the keys, or nesting
+    auxiliary config (key alias, keystore `type`, `proxyVerify` toggle) *inside* the `secret:` block.
+    Reuse the canonical `inlineSecret` / `existingSecret` / `existingSecretKey` block (Pattern 6);
+    auxiliary keys are siblings of `secret:`, not children. See ADR-0068.
+
 ---
 
 ## Resources
@@ -286,6 +326,7 @@ using the layer availability table in `docs/skills/integration-test-scenario-res
 - helm-docs annotation format: <https://github.com/norwoodj/helm-docs>
 - Chart design principles: `docs/index.md`
 - Values YAML policy (canonical): `docs/policies/values-yaml-policy.md`
+- Standardized secret interface: `docs/adr/0068-standardize-existingsecret-input-interface-across-all-helm.md`
 - Breaking changes policy: `docs/policies/breaking-changes.md`
 - Primary values file: `charts/<version>/values.yaml`
 - Schema file: `charts/<version>/values.schema.json`

@@ -247,6 +247,7 @@ When opening a PR with `gh pr create`, **do NOT** use the built-in
 
 ## Additional Agent Context
 - `CLAUDE.md` — thin redirect for Claude Code (redirects to this file, AGENTS.md)
+- `.github/instructions/*.instructions.md` — **authoritative path-scoped chart-coding conventions.** These files carry Copilot/VS Code `applyTo:` globs that are NOT auto-applied by Claude Code, so read the matching guide explicitly BEFORE editing: `values-yaml.instructions.md` (values.yaml authoring — `@param` conjunctions, secret-block shape), `helm-templates.instructions.md` (templates, NOTES.txt, constraints/warnings), `code-review.instructions.md`, `go-tests.instructions.md`, `scripting.instructions.md`, `github-actions.instructions.md`.
 - `.github/AGENTS.md` — CI/CD architecture, repo structure, values files
 - `docs/AGENTS.md` — **ADR authoring rules**. Read before drafting, amending, or reviewing any ADR. Points to `docs/adr/TEMPLATE.md` (structure) and `docs/maintainer-guide.md` (process).
 - `SKILLS.md` — deploy-camunda CLI patterns, kubectl usage