diff --git a/AGENTS.md b/AGENTS.md
index d587d8230..2fb36fb70 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,7 @@ Detailed guides for specific subsystems live in `contrib/claude/`:
 - [`contrib/claude/relay.md`](contrib/claude/relay.md) — Frontend Relay client (queries, fragments, mutations, pagination)
 - [`contrib/claude/react-components.md`](contrib/claude/react-components.md) — React component shape (file/export, props, configure vs data via hooks)
 - [`contrib/claude/ui.md`](contrib/claude/ui.md) — @probo/ui, Tailwind, tailwind-variants, folders, skeletons, compound components
+- [`contrib/claude/config.md`](contrib/claude/config.md) — Configuration propagation (all files to update when config changes)
 - [`contrib/claude/commit.md`](contrib/claude/commit.md) — Commit message conventions
 - [`contrib/claude/license.md`](contrib/claude/license.md) — ISC license header (all file types)
 - [`contrib/claude/release.md`](contrib/claude/release.md) — Release process (version bump, changelog, tag, push)
diff --git a/contrib/claude/config.md b/contrib/claude/config.md
new file mode 100644
index 000000000..ed0ce0fe5
--- /dev/null
+++ b/contrib/claude/config.md
@@ -0,0 +1,52 @@
+# Configuration Propagation
+
+When a configuration field is added, renamed, or removed in the Go config structs, **all** downstream consumers must be updated in the same change. The config struct in `pkg/probod/` is the source of truth.
+
+## Files to update (checklist)
+
+| # | File | Role |
+|---|------|------|
+| 1 | `pkg/probod/*.go` | Go config structs — source of truth |
+| 2 | `pkg/probod/probod.go` `New()` | Default values for new fields |
+| 3 | `pkg/bootstrap/builder.go` | Env-var → struct mapping (`Build()` method) |
+| 4 | `pkg/bootstrap/builder.go` | Required-env validation (`validateRequired()`) |
+| 5 | `cfg/dev.yaml` | Local development config |
+| 6 | `e2e/console/testdata/config.yaml` | E2E test config |
+| 7 | `contrib/lima/provision.sh` | Sandbox env vars passed to `probod-bootstrap` |
+| 8 | `contrib/helm/charts/probo/values.yaml` | Helm default values |
+| 9 | `contrib/helm/charts/probo/values-production.yaml.example` | Helm production template |
+| 10 | `contrib/helm/charts/probo/templates/deployment.yaml` | Helm deployment — maps values → env vars |
+| 11 | `contrib/helm/charts/probo/templates/secret.yaml` | Helm secret — sensitive values |
+
+## Flow
+
+```
+Go struct (pkg/probod/)
+  │
+  ├─► probod New() defaults
+  │
+  ├─► bootstrap builder.go (env var → struct)
+  │     │
+  │     ├─► cfg/dev.yaml              (static YAML, local dev)
+  │     ├─► e2e/console/testdata/     (static YAML, tests)
+  │     ├─► contrib/lima/provision.sh  (env vars → probod-bootstrap)
+  │     └─► Helm chart
+  │           ├─ values.yaml           (user-facing knobs)
+  │           ├─ values-production.yaml.example
+  │           ├─ templates/deployment.yaml (values → env vars)
+  │           └─ templates/secret.yaml     (sensitive values)
+  │
+  └─► probod.go Run() (wiring into services)
+```
+
+## Rules
+
+1. **Never add a Go config field without updating every file in the checklist.**
+2. **Env var naming** — follow the existing convention in `builder.go`: `SECTION_FIELD_NAME` (e.g. `AUTH_COOKIE_DOMAIN`, `CUSTOM_DOMAINS_RENEWAL_INTERVAL`).
+3. **Secrets** go through `secret.yaml` and are referenced via `secretKeyRef` in `deployment.yaml`. Non-secret values are set inline.
+4. **`cfg/dev.yaml`** uses safe, non-production defaults (plaintext passwords, `localhost`, `secure: false`).
+5. **`e2e/console/testdata/config.yaml`** mirrors `cfg/dev.yaml` but with test-specific values (different ports, `probod_test` DB, shorter intervals).
+6. **`provision.sh`** only sets env vars that differ from `builder.go` defaults (e.g. `PROBOD_BASE_URL`, `AUTH_COOKIE_DOMAIN`, `AUTH_COOKIE_SECURE`). If the new field's default is acceptable in the sandbox, no env var is needed.
+7. **Helm `values.yaml`** exposes the field under the appropriate `probo.*` key with a sensible default. `values-production.yaml.example` includes it only when the production value differs or the user must set it.
+8. **Optional features** (custom domains, SAML, connectors, tracing) are gated by `{{- if }}` blocks in the Helm templates; follow the same pattern for new optional fields.
+9. **Bootstrap tests** (`pkg/bootstrap/builder_test.go`) must cover the new env var mapping.