diff --git a/template-catalog/templates/ess.mdx b/template-catalog/templates/ess.mdx
index 622344f..30517a1 100644
--- a/template-catalog/templates/ess.mdx
+++ b/template-catalog/templates/ess.mdx
@@ -166,7 +166,9 @@ essConfig:
     # - name: gcp-discover
     #   provider: my-gcp
     #   discoverAllSecrets: true      # GCP only — creates one Control Plane secret per project secret;
-    #                                 # each secret's "cpln-type" label (opaque|dictionary) sets the type
+    #                                 # each secret's "cpln-type" label (opaque|dictionary) sets the type;
+    #                                 # base64 values are auto-marked "encoding: base64" unless the GCP
+    #                                 # secret is labeled "cpln-encoding: disable"
     # - name: infisical-secret
     #   provider: my-infisical
     #   opaque: dev/DATABASE_URL       # format: "<environmentID>/<secret>"
@@ -376,6 +378,10 @@ The type of each created secret is controlled by a `cpln-type` **label** on the
 - `cpln-type: dictionary` — the value is parsed as JSON and flattened into a Control Plane `dictionary` secret (same flattening rules as `dictionaryFromJson`, including the `__raw` fallback for non-JSON values).
 - `cpln-type: opaque` (or no label) — stored as a Control Plane `opaque` secret.
 
+Opaque values that are canonical base64 are automatically marked `encoding: base64` on the created Control Plane secret, so the payload is decoded when workloads consume it. Surrounding whitespace (such as a trailing newline from `... | base64 | gcloud ...`) is trimmed from the stored payload. Detection can be switched off per secret with a `cpln-encoding` **label** on the GCP secret:
+
+- `cpln-encoding: disable` — the value is stored verbatim and never marked `encoding: base64`. Use this for plain values that happen to look like base64 (for example, a 16-character alphanumeric API key).
+
 Each Control Plane secret is named after its GCP secret, normalized to a valid Control Plane name (lowercased, with unsupported characters such as `_` replaced by `-` — e.g. `MY_API_KEY` → `my-api-key`). If two names normalize to the same value, the last one wins and a warning is logged. Created secrets carry a `syncer.cpln.io/discoveredBy` tag set to this entry's `name`. Secrets with no accessible latest version (no versions, disabled, or destroyed) are skipped.
 
 <Note>