zuplo 7.6.5 → 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/getting-started.mdx

@@ -2,13 +2,13 @@
 title: Zuplo AI Gateway Getting Started
 sidebar_label: Getting Started
 description:
-  Set up your first AI Gateway project. Connect a Git repository, configure an
-  AI provider, create a team and an app, review the app's policy chain, and make
-  your first LLM request through Zuplo.
+  Set up your first AI Gateway project. Configure an AI provider, create a team
+  and an app, review the app's policy chain, and make your first LLM request
+  through Zuplo.
 ---
 
 This guide walks you through setting up your first AI Gateway project, from
-connecting a Git repository to making your first LLM request through Zuplo.
+creating the project to making your first LLM request through Zuplo.
 
 A Zuplo account contains your members and one or more projects. The AI Gateway
 you create in this guide is a Zuplo project; its providers, teams, and apps all
@@ -19,7 +19,6 @@ account, Zuplo project, and AI Gateway team roles control access.
 ## Prerequisites
 
 - A Zuplo account (sign up free at [zuplo.com](https://zuplo.com))
-- A Git provider account that can create repositories (this guide uses GitHub)
 - An API key for at least one LLM provider (OpenAI, Anthropic, Google, Mistral,
   xAI, etc.)—or none at all, if you start with the free
   [Zuplo Demo provider](./providers.mdx#zuplo-demo)
@@ -28,52 +27,32 @@ account, Zuplo project, and AI Gateway team roles control access.
 
 1. **Create an AI Gateway project**
 
-   Log into the [Zuplo Portal](https://portal.zuplo.com), navigate to
-   **Projects**, and click **New Project**. Choose **Configure an AI gateway**,
-   give your project a name (for example, "MyCompany AI Gateway"), and click
-   **Create Project**.
+   Sign in to the [Zuplo Portal](https://portal.zuplo.com), navigate to
+   **Projects**, and click **New Project**. Choose **AI Gateway**, give your
+   project a name (for example, "MyCompany AI Gateway"), and click **Create
+   Project**.
 
-2. **Connect the project to a Git repository**
-
-   Your AI Gateway deploys from source control, so the first step after creating
-   the project is connecting it to a repository. The project shows a **Let's Get
-   You Deployed** screen until a repository is connected.
-
-   Zuplo supports GitHub, GitLab, Bitbucket, and Azure DevOps. This guide uses
-   GitHub, which is the only provider with automatic deployments—see
-   [Source Control and Deployment](../concepts/source-control-and-deployment.mdx)
-   for the other providers, which deploy through the Zuplo CLI in your own CI/CD
-   pipeline.
-
-   With GitHub, click **Create New Repo** to open GitHub with the repository
-   name prefilled, create the repository, then return to the Zuplo Portal and
-   select the repository to connect it. Zuplo adds the gateway's source to the
-   repository and deploys it. After that, pushes to your default branch deploy
-   to production.
-
-   To work with the gateway's source later—for example, to add
-   [custom policies](./custom-policies.mdx)—clone the repository:
-
-   ```bash
-   git clone https://github.com/your-org/your-gateway-repo.git
-   ```
+   The portal shows **Setting up your gateway…** while it provisions the
+   project. When that's done, the project homepage opens with a setup checklist
+   for a provider, a team, and an app—the same path as this guide. Follow these
+   steps; you can tick the checklist as you go or ignore it. The gateway is
+   already deployed, so you can continue with this guide.
 
    :::note
 
-   If your default branch requires pull requests, Zuplo pushes the gateway
-   source to a setup branch and shows you a pull request to merge. The project
-   finishes connecting once the pull request lands on the default branch.
+   Connect a repository later if you want to write
+   [custom policies](./custom-policies.mdx) or manage the gateway's source in
+   Git. Open
+   [**Settings → Source Control**](https://portal.zuplo.com/+/account/project/ai/settings/source-control).
+   See [Source Control](./source-control.mdx).
 
    :::
 
-   See [Source Control](./source-control.mdx) for what the repository contains
-   and how deployments work.
-
-3. **Configure a provider**
+2. **Configure a provider**
 
-   Providers are the LLM services (like OpenAI or Anthropic) that your apps use.
-   You configure these once as an administrator, and your team members use them
-   without needing direct access to provider API keys.
+   Providers are the LLM services (such as OpenAI or Anthropic) that your apps
+   use. You configure these once as an administrator, and your team members use
+   them without needing direct access to provider API keys.
 
    Open
    [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
@@ -96,7 +75,7 @@ account, Zuplo project, and AI Gateway team roles control access.
    full list of supported providers, including OpenAI-compatible custom
    providers.
 
-4. **Create a team**
+3. **Create a team**
 
    Teams organize users and carry their own budget rules and policy templates.
    Even if you're starting solo, you need at least one team.
@@ -104,13 +83,15 @@ account, Zuplo project, and AI Gateway team roles control access.
    Open the **Apps & Teams** tab and click **New Team**. Name your team (for
    example, "Root" or your company name), choose an icon, and click **Create
    Team**. This is your first team, so there's no parent picker yet—it appears
-   on later teams, letting you nest them. To set gateway-wide spending limits
-   across this Zuplo project, open the gateway's **Settings → Usage Limits**.
-   Team budgets—shared and per-expression—are set on the team's **Usage &
-   Limits** tab. See [Usage Limits](./usage-limits.mdx). Gateway and team limits
-   apply to every app regardless of its policy chain.
+   on later teams, letting you nest them.
 
-5. **Create an app**
+   To set gateway-wide spending limits across this Zuplo project, open the
+   gateway's **Settings → Usage Limits**. Team budgets—shared and
+   per-expression—are set on the team's **Usage & Limits** tab. See
+   [Usage Limits](./usage-limits.mdx). Gateway and team limits apply to every
+   app regardless of its policy chain.
+
+4. **Create an app**
 
    Apps represent individual software applications or services that call the AI
    Gateway. Each app gets its own unique URL and API key.
@@ -129,7 +110,7 @@ account, Zuplo project, and AI Gateway team roles control access.
 
    :::
 
-6. **Review the app's policy chain**
+5. **Review the app's policy chain**
 
    The portal opens the app's **Policies** tab, which shows the app's policy
    chain—the ordered list of policies that run on each request. No policy is
@@ -137,15 +118,17 @@ account, Zuplo project, and AI Gateway team roles control access.
    picks its own model as `providerName/model`, from any model your providers
    expose.
 
-   To restrict that, add the **Model Filtering** policy and give it an allow
-   list such as `openai/gpt-5-mini`. Requests may then use only listed models,
-   and the first entry becomes the default when a request omits `model`.
+   To restrict that, click **Add policy**, select **Model Filtering**, and give
+   it an allow list of models you enabled in the provider step—for example
+   `openai/gpt-5-mini` if you added OpenAI, or `zuplodemo/pirate` if you are
+   using only Zuplo Demo. Requests may then use only listed models, and the
+   first entry becomes the default when a request omits `model`.
 
    :::caution{title="An unrestricted app can reach every model you configured"}
 
    Without Model Filtering, an app may call any model available through the
    providers configured for this Zuplo project, including expensive ones. Add
-   Model Filtering for any app that should be limited to a specific set.
+   Model Filtering for any app that you want limited to a specific set.
 
    :::
 
@@ -153,7 +136,7 @@ account, Zuplo project, and AI Gateway team roles control access.
    guardrails, and any custom policies. Changes to the chain apply within about
    a minute—no redeploy needed. See [Policy Chains](./policy-chains.mdx).
 
-7. **Get the app's URL and API key**
+6. **Get the app's URL and API key**
 
    The app's **API URL** is shown in full at the top of the app page, and its
    key lives on the app's **API Key** tab. The API URL is the gateway's hostname
@@ -190,12 +173,12 @@ account, Zuplo project, and AI Gateway team roles control access.
    export ZUPLO_APP_API_KEY="<the API key from the app page>"
    ```
 
-8. **Send your first request from the Playground**
+7. **Send your first request from the Playground**
 
    Click **Playground** in the app's header to open it. It chats with the app's
    own gateway URL and API key, so it exercises the same policy chain your code
-   will hit—without wiring up a client first. The button sits on every app tab,
-   so you can try a request while editing policies without losing your place.
+   hits—without wiring up a client first. The button sits on every app tab, so
+   you can try a request while editing policies without losing your place.
 
    Pick a model from the selector, optionally set a system prompt, and send a
    message. The playground shows the cURL for the next request, and **Copy
@@ -205,6 +188,9 @@ account, Zuplo project, and AI Gateway team roles control access.
 
 </Stepper>
 
+You now have a working AI Gateway: a provider, a team, an app, and a chat
+completion through the app's URL.
+
 ## Integrate with your own code
 
 Once the Playground works, configure your own code with the same URL and key.
@@ -221,7 +207,7 @@ for the [OpenAI SDK](./integrations/openai.mdx),
 ```javascript
 import OpenAI from "openai";
 
-// Old approach - directly calling OpenAI
+// Direct OpenAI
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
 });
@@ -239,11 +225,10 @@ console.log(completion.choices[0].message.content);
 ```javascript
 import OpenAI from "openai";
 
-// New approach - using Zuplo AI Gateway
+// Through the AI Gateway
 const openai = new OpenAI({
   apiKey: process.env.ZUPLO_APP_API_KEY,
-  baseURL:
-    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+  baseURL: process.env.ZUPLO_APP_BASE_URL,
 });
 
 const completion = await openai.chat.completions.create({
@@ -256,7 +241,7 @@ console.log(completion.choices[0].message.content);
 
 Run the example with `node sample.mjs`.
 
-### What changed?
+### Changes to make
 
 1. **URL**: Replace your provider's URL with your app's gateway URL from the app
    page
@@ -296,8 +281,7 @@ curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bc
 4. Click **View in Analytics** on the Metrics frame for the full request-level
    breakdown, already filtered to this app.
 
-You should see your test request appear with token usage and performance
-metrics.
+Your test request appears with token usage and performance metrics.
 
 ## Next steps
 
@@ -305,6 +289,8 @@ metrics.
   caching, and guardrails to your app's chain
 - [Custom Policies](./custom-policies.mdx): write your own policy and add it to
   an app's chain
+- [Source Control](./source-control.mdx): connect a Git repository when you want
+  to edit the gateway's source or write custom policies
 - [Policy Templates](./policy-templates.mdx): give every new app in a team a
   consistent starting chain
 - [Usage Limits](./usage-limits.mdx): set spending limits for the gateway,

package/docs/ai-gateway/overview.mdx

@@ -2,9 +2,9 @@
 title: AI Gateway overview
 sidebar_label: Overview
 description:
-  The Zuplo AI Gateway is a proxy between your apps and LLM providers, deployed
-  from your own Git repository, with per-app policy pipelines for cost control,
-  model access, guardrails, and observability.
+  The Zuplo AI Gateway is a proxy between your apps and LLM providers, with
+  per-app policy pipelines for cost control, model access, guardrails, and
+  observability.
 ---
 
 Zuplo's AI Gateway acts as an intelligent proxy layer that sits between your
@@ -84,10 +84,11 @@ capabilities. Apps reference models as `providerName/model`—for example
 
 ### Source-Controlled Gateway
 
-Every AI Gateway project connects to a Git repository that contains the
-gateway's routes and policy declarations. The default branch is what production
-runs, so gateway changes go through your normal review workflow. See
-[Source Control](./source-control.mdx).
+A new AI Gateway project deploys without a Git repository, so you can configure
+providers, teams, and apps right away. Connect a
+[Git repository](./source-control.mdx) when you want to write custom policies or
+review gateway changes in Git. After you connect, the default branch is what
+production runs.
 
 ### Per-App Policy Chains
 

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/ai-gateway/source-control.mdx

@@ -2,25 +2,28 @@
 title: AI Gateway Source Control
 sidebar_label: Source Control
 description:
-  Every AI Gateway project deploys from a Git repository you own. Learn what the
-  scaffolded repository contains, how pushes deploy to production, and which
-  changes require a deploy versus applying live.
+  A new AI Gateway project deploys without Git. Connect a repository to write
+  custom policies, review gateway source, and deploy from your default branch.
 ---
 
-An AI Gateway is a Zuplo project configured for AI traffic. Every AI Gateway
-project is backed by a Git repository that you own. The repository contains the
-gateway's routes and policy declarations, so gateway changes go through your
-normal review workflow, and custom policies are plain TypeScript files you
-commit alongside them.
+An AI Gateway is a Zuplo project configured for AI traffic. A new project
+deploys automatically, so you can configure providers, teams, and apps without
+connecting a Git repository. Connect one when you want to write
+[custom policies](./custom-policies.mdx), review gateway changes in Git, or
+deploy from your own CI/CD.
 
-## Connecting a repository
+The repository contains the gateway's routes and policy declarations. Custom
+policies are plain TypeScript files you commit alongside them.
+
+## Connect a repository
 
-A new AI Gateway project must be connected to a repository before it can deploy.
 Zuplo supports GitHub, GitLab, Bitbucket, and Azure DevOps—see
 [Source Control and Deployment](../concepts/source-control-and-deployment.mdx)
 for what each provider supports.
 
-The project shows a **Let's Get You Deployed** screen with two options:
+Open
+[**Settings → Source Control**](https://portal.zuplo.com/+/account/project/ai/settings/source-control)
+and choose one of the following:
 
 - **Create New Repo** starts a new repository with the name prefilled. With
   GitHub, this opens GitHub directly; create the repository, then return to the
@@ -28,14 +31,28 @@ The project shows a **Let's Get You Deployed** screen with two options:
 - Connect an existing repository. Use an empty one so the gateway's source has
   the repository to itself.
 
-When you connect, Zuplo adds the gateway's source to the repository, pushes it,
-and starts the first production deployment.
+When you connect, Zuplo adds the gateway's source to the repository and pushes
+it. The first push rebuilds production from that source. After that, with
+GitHub, pushes to your default branch deploy to production.
+
+Until you connect a repository, production runs the gateway template Zuplo
+deploys at project creation. Connecting a repository doesn't replace that
+production URL; the first source deploy reuses it.
+
+To work with the source locally, clone the repository:
+
+```bash
+git clone https://github.com/GITHUB_ORG/REPO_NAME.git
+```
+
+Replace `GITHUB_ORG` with your GitHub organization or user, and `REPO_NAME` with
+the repository name.
 
 :::note
 
 If your default branch requires pull requests, Zuplo pushes the gateway source
-to a setup branch and surfaces a pull request for you to merge. The first
-deployment starts once the pull request lands on the default branch.
+to a setup branch and surfaces a pull request for you to merge. The project
+finishes connecting once the pull request lands on the default branch.
 
 :::
 
@@ -56,13 +73,13 @@ Add custom policy modules under `modules/` and declare them in
 
 ## How deployments work
 
-The repository's default branch is what production runs. With GitHub, every push
-to it deploys automatically. With GitLab, Bitbucket, and Azure DevOps, your own
-CI/CD pipeline deploys by calling `zuplo deploy`—see
+After you connect a repository, its default branch is what production runs. With
+GitHub, every push to it deploys automatically. With GitLab, Bitbucket, and
+Azure DevOps, your own CI/CD pipeline deploys by calling `zuplo deploy`—see
 [Source Control and Deployment](../concepts/source-control-and-deployment.mdx).
 
-There is no in-portal code editor for AI Gateway projects—the repository is the
-source of truth, and you edit it with your normal tools.
+After you connect, the **Code** tab opens the gateway's source. You can also
+clone the repository and edit it with your normal tools.
 
 Three categories of changes take effect differently:
 

package/docs/concepts/ai-gateway.mdx

@@ -55,12 +55,12 @@ code change.
 
 ## How it fits into Zuplo
 
-An AI Gateway is a type of Zuplo project. Its routes and policy declarations
-live in a [Git repository](../ai-gateway/source-control.mdx), so gateway changes
-go through the same review workflow as the rest of your Zuplo configuration, and
-the providers, teams, and apps you configure belong to that project. The
-platform primitives — deployment model, environments, analytics — are the same
-ones described in [How Zuplo Works](./how-zuplo-works.mdx).
+An AI Gateway is a type of Zuplo project. A new project deploys without a Git
+repository; you can [connect a repository](../ai-gateway/source-control.mdx)
+later so gateway changes go through the same review workflow as the rest of your
+Zuplo configuration. The providers, teams, and apps you configure belong to that
+project. The platform primitives — deployment model, environments, analytics —
+are the same ones described in [How Zuplo Works](./how-zuplo-works.mdx).
 
 ## Next steps
 

package/docs/dev-portal/zudoku/configuration/api-reference.md

@@ -276,7 +276,7 @@ Available options:
   schemes section on the info page, and the Authorize dialog in the playground). Disabled by default
   (`true`). Set to `false` to enable security scheme support
 - `disableMcpAuthInstructions`: Hide the authentication instructions on
-  [MCP server](../guides/mcp-servers.md) endpoints. The MCP card normally derives a credential
+  [MCP server](/docs/dev-portal/documenting-mcp-servers) endpoints. The MCP card normally derives a credential
   header from the operation's security scheme and shows it in every install snippet. Set to `true`
   to render the server as unauthenticated instead — no header snippets and no "replace
   `YOUR_API_KEY`" steps

package/docs/dev-portal/zudoku/configuration/llms.md

@@ -112,10 +112,6 @@ dist/
     └── ...
 ```
 
-On Vercel builds, this tree is written beneath `.vercel/output/static/` instead of `dist/`. The
-deployed public URLs remain the same. See the [Vercel deployment guide](/dev-portal/zudoku/deploy/vercel) for the
-generated routing and Markdown content-negotiation behavior.
-
 **Important:** Individual `.md` files are only kept in the final build if `publishMarkdown: true`.
 If only `llmsTxt` or `llmsTxtFull` is enabled, the `.md` files are generated temporarily during the
 build but deleted after the `llms.txt` files are created.

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.5",
+  "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.5",
-    "@zuplo/core": "7.6.5",
-    "@zuplo/runtime": "7.6.5",
-    "@zuplo/test": "7.6.5"
+    "@zuplo/cli": "7.6.7",
+    "@zuplo/core": "7.6.7",
+    "@zuplo/runtime": "7.6.7",
+    "@zuplo/test": "7.6.7"
   }
 }