zuplo 7.6.6 → 7.6.7

package/docs/ai-gateway/custom-policies.mdx

@@ -171,8 +171,9 @@ options exactly.
 
 ## Configure credentials
 
-If a policy needs a credential—say it calls an external moderation API—set it in
-the declaration's options, and let chain entries inherit it:
+If a policy needs a credential—say it calls an external moderation API—store it
+as an [environment variable](../articles/environment-variables.mdx) and
+reference it with `$env(...)` in the declaration's options:
 
 ```json title="config/policies.json"
 {
@@ -182,14 +183,17 @@ the declaration's options, and let chain entries inherit it:
     "export": "default",
     "module": "$import(./modules/my-moderation-policy)",
     "options": {
-      "apiKey": "your-moderation-api-key"
+      "apiKey": "$env(MODERATION_API_KEY)"
     }
   }
 }
 ```
 
 Leave the chain entry's options out so it inherits the declaration's values—an
-entry that sets its own options replaces them completely.
+entry that sets its own options replaces them completely. An entry that does set
+its own options can use `$env(...)` references too, so one declared policy can
+read a different credential or setting per app. See
+[Options and secrets](./policy-chains.mdx#options-and-secrets).
 
 ## Beyond filtering
 

package/docs/ai-gateway/policy-chains.mdx

@@ -90,8 +90,27 @@ an entry with empty options replaces the declared options with an empty object,
 which breaks a policy that has required settings. Omit options entirely to
 inherit.
 
-Keep credentials in the declaration's options and let entries inherit them, so
-the gateway's repository—not app configuration—holds them. See
+Entry options may reference
+[environment variables](../articles/environment-variables.mdx) with
+`$env(VAR_NAME)`, exactly as in `policies.json`. The gateway resolves each
+reference when the chain runs, so a per-app entry can carry its own
+environment-backed value:
+
+```json
+{
+  "name": "my-moderation-policy",
+  "options": {
+    "apiKey": "$env(MODERATION_API_KEY)",
+    "threshold": 0.8
+  }
+}
+```
+
+A reference to an unset variable fails the request with a configuration error
+naming the variable—it never silently resolves to an empty string.
+
+Alternatively, keep credentials in the declaration's options and let entries
+inherit them, so the gateway's repository—not app configuration—holds them. See
 [Configure credentials](./custom-policies.mdx#configure-credentials).
 
 ## Recommended order

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -535,9 +535,33 @@ From a chain policy you can:
 
 ## Store secrets safely
 
-Keep credentials and other environment-backed values in the pre-declared
-policy's `handler.options`, then omit `options` from the application chain entry
-to inherit them:
+Application chain options can reference project environment variables. Use a
+standalone reference when the complete option value comes from one variable, or
+embed one or more references in a larger string:
+
+```json
+{
+  "inboundPolicyChain": [
+    {
+      "name": "my-ai-guardrail",
+      "options": {
+        "apiKey": "$env(MY_GUARDRAIL_API_KEY)",
+        "authorization": "Bearer $env(MY_GUARDRAIL_API_KEY)"
+      }
+    }
+  ]
+}
+```
+
+The executor resolves `$env(NAME)` references when it instantiates an enabled
+chain entry. Resolution visits string values recursively through nested objects
+and arrays. Object keys remain literal. If a referenced variable is missing or
+restricted, the executor rejects the configuration with an error that identifies
+the variable and the chain entry; it never substitutes an empty string.
+
+To share the same environment-backed options across applications, keep them in
+the pre-declared policy's `handler.options`, then omit `options` from the
+application chain entry to inherit them:
 
 ```json
 {
@@ -563,9 +587,9 @@ to inherit them:
 }
 ```
 
-Do not place `$env(...)` expressions in application configuration. Environment
-references are resolved when gateway configuration is built, while application
-chains are evaluated when a request arrives.
+Declared `handler.options` use the normal build-time environment resolution.
+Application entry options are resolved at runtime and replace the declaration's
+complete options object; the two objects are not merged.
 
 ## Chain entry reference
 
@@ -578,8 +602,8 @@ Every chain entry supports:
   without running it. Omitted or `true` entries run normally.
 
 Disabled entries are still validated. They must be well-formed, name a declared
-policy, contain no literal `$env(...)` value, and cannot select the
-configuration loader or executor.
+policy, and cannot select the configuration loader or executor. Their options
+are not instantiated, so their environment references are not resolved.
 
 The executor permits repeated entries and cannot infer the behavior of custom or
 wrapper policies. Configuration authors are responsible for avoiding repeated
@@ -606,7 +630,9 @@ Before deploying:
 1. Declare every selectable policy in `config/policies.json`.
 2. Configure application and team policy templates with the policies each app
    may edit or remove.
-3. Put environment-backed values in declared policy options.
+3. Put shared environment-backed values in declared policy options, or use
+   `$env(...)` in application entry option values when each application needs
+   its own complete options object.
 4. Place the configuration loader before the executor on every AI Gateway route
    (or the executor alone when you prefer the combined path). Add AI Gateway
    Authentication to an application's chain for that app only, or before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.6",
+  "version": "7.6.7",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.6",
-    "@zuplo/core": "7.6.6",
-    "@zuplo/runtime": "7.6.6",
-    "@zuplo/test": "7.6.6"
+    "@zuplo/cli": "7.6.7",
+    "@zuplo/core": "7.6.7",
+    "@zuplo/runtime": "7.6.7",
+    "@zuplo/test": "7.6.7"
   }
 }