zuplo 7.6.2 → 7.6.4

package/docs/ai-gateway/managing-apps.mdx

@@ -86,10 +86,11 @@ over—see [Dynamic model routing](./cookbooks/dynamic-model-routing.mdx).
 ## Setting budgets
 
 App budgets live on the **Budgets and Costs** policy in the app's chain. Open
-the app's **Policies** tab and configure it with daily or monthly limits for
-spending, tokens, or requests. Team and gateway limits apply to every app
-automatically, even when the app's chain doesn't include Budgets and Costs. See
-[Usage Limits](./usage-limits.mdx).
+the app's **Policies** tab and add budget rules capping spending, tokens, or
+requests over an hourly, daily, weekly, or monthly period—either for the app as
+a whole or per metadata value, so each caller gets its own budget. Team and
+gateway limits apply to every app automatically, even when the app's chain
+doesn't include Budgets and Costs. See [Usage Limits](./usage-limits.mdx).
 
 ## Editing an App
 

package/docs/ai-gateway/managing-providers.mdx

@@ -51,9 +51,11 @@ To add a new AI provider to your Zuplo AI Gateway, follow these steps:
    create an API key for each provider see the
    [provider documentation](./providers.mdx). The
    [Zuplo Demo provider](./providers.mdx#zuplo-demo) asks for no API key—your
-   gateway authenticates to the demo service itself, and
+   gateway authenticates to the demo service itself,
    [Bedrock Mantle](./bedrock-mantle.mdx) additionally asks for an **AWS
-   Region** and accepts only long-term Bedrock API keys.
+   Region** and accepts only long-term Bedrock API keys, and
+   [Vertex AI](./vertex-ai.mdx) asks for a **Location** and a **Google Cloud
+   Project ID** and takes a service account JSON key file instead of an API key.
 
 1. Select the model or models you want to use with this provider. The available
    models will depend on the selected provider. This can be changed later.
@@ -83,10 +85,12 @@ To modify an existing provider, open
 and click the **Edit** button next to the provider you want to modify.
 
 You can modify the API key and selected models for the provider—and, for
-[Bedrock Mantle](./bedrock-mantle.mdx), the AWS Region. The **Provider Name**
-isn't editable: it's the routing address in every `providerName/model`
-reference, so renaming it would orphan each stored reference to this provider.
-After making your changes, click **Save** to apply them.
+[Bedrock Mantle](./bedrock-mantle.mdx), the AWS Region, or for
+[Vertex AI](./vertex-ai.mdx), the Location and Google Cloud Project ID. The
+**Provider Name** isn't editable: it's the routing address in every
+`providerName/model` reference, so renaming it would orphan each stored
+reference to this provider. After making your changes, click **Save** to apply
+them.
 
 :::caution
 

package/docs/ai-gateway/managing-teams.mdx

@@ -39,7 +39,7 @@ click **Create Sub-Team** in the team's header.
 
 After creating a team, use its tabs to configure it:
 
-- **Policies**—the team's [policy template](./policy-templates.mdx), the
+- **Policy Template**—the team's [policy template](./policy-templates.mdx), the
   starting policy chain for apps created in the team.
 - **Usage & Limits**—spending limits that apply to all of the team's apps
   combined. See [Usage Limits](./usage-limits.mdx).

package/docs/ai-gateway/overview.mdx

@@ -76,11 +76,11 @@ usage limits still apply.
 
 Configure multiple LLM providers within a single AI Gateway project. Supported
 providers include OpenAI, Anthropic, Google, Mistral, xAI, Amazon Bedrock
-(through [Bedrock Mantle](./bedrock-mantle.mdx)), and OpenAI-compatible custom
-providers. See [AI Providers](./providers.mdx) for the full list of providers
-and supported capabilities. Apps reference models as `providerName/model`—for
-example `openai/gpt-5-mini`—so a single app can use models from several
-providers.
+(through [Bedrock Mantle](./bedrock-mantle.mdx)), Google Cloud
+([Vertex AI](./vertex-ai.mdx)), and OpenAI-compatible custom providers. See
+[AI Providers](./providers.mdx) for the full list of providers and supported
+capabilities. Apps reference models as `providerName/model`—for example
+`openai/gpt-5-mini`—so a single app can use models from several providers.
 
 ### Source-Controlled Gateway
 

package/docs/ai-gateway/providers.mdx

@@ -3,8 +3,8 @@ title: AI Providers
 sidebar_label: Overview
 description:
   The AI providers and capabilities the Zuplo AI Gateway supports, including
-  OpenAI, Anthropic, Google, Mistral, xAI, and OpenAI-compatible custom
-  providers.
+  OpenAI, Anthropic, Google, Vertex AI, Mistral, xAI, and OpenAI-compatible
+  custom providers.
 ---
 
 Zuplo's AI Gateway supports integration with various AI providers, allowing you
@@ -21,6 +21,8 @@ Zuplo currently supports the following AI providers:
 - xAI (Grok)
 - [Bedrock Mantle](./bedrock-mantle.mdx)—Amazon Bedrock's compatible-APIs
   endpoint, serving Claude models and models from many other vendors
+- [Vertex AI](./vertex-ai.mdx)—Google Cloud's managed model platform, serving
+  Gemini and Model Garden models on your own Google Cloud project
 - [Zuplo Demo](#zuplo-demo)—a free, keyless provider for trying the gateway
 - OpenAI-compatible [Custom Providers](./custom-providers.mdx) (such as Qwen,
   Kimi, etc)
@@ -35,6 +37,7 @@ The following capabilities are supported across providers:
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
+| Vertex AI                  | ✅               | ✅         | ❌        | ❌       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
 | OpenAI-compatible (Custom) | ✅               | ✅         | ❌        | ❌       |
 
@@ -77,6 +80,32 @@ instead of an endpoint URL, and it accepts only long-term Bedrock API keys,
 which start with `ABSK`. For prerequisites, setup steps, code examples, and
 troubleshooting, see [Using Bedrock Mantle](./bedrock-mantle.mdx).
 
+## Vertex AI
+
+**Vertex AI** is Google Cloud's managed model platform. One provider
+configuration serves both the Gemini family and Vertex's Model Garden partner
+models—DeepSeek, Qwen, GLM, Kimi, MiniMax, Gemma, and GPT-OSS—from your own
+Google Cloud project, on your Google Cloud billing.
+
+Two things make its setup different from every other provider:
+
+- **It authenticates with a service account, not an API key.** Vertex's
+  prediction endpoints reject API keys, so the dialog asks for a service account
+  JSON key file and the gateway exchanges it for short-lived access tokens.
+- **It needs a Google Cloud project as well as a location.** Vertex endpoints
+  are per-location, and the project isn't part of the endpoint, so the dialog
+  asks for both.
+
+Every Vertex model ID is publisher-qualified, so a model reference has two
+slashes: a provider named `vertexai` serves `vertexai/google/gemini-3.7-flash`
+and `vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`. Model availability
+varies by location—most Model Garden models are served only from the `global`
+location. Vertex also hosts Anthropic's Claude models, but on a different API
+surface that the gateway doesn't route to.
+
+For prerequisites, Google Cloud setup, provider steps, code examples, and
+troubleshooting, see [Using Vertex AI](./vertex-ai.mdx).
+
 ## Zuplo Demo
 
 **Zuplo Demo** is a free provider that Zuplo operates so you can try the AI

package/docs/ai-gateway/usage-limits.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Usage Limits & Thresholds"
+title: "Usage Limits & Budget Rules"
 sidebar_label: "Usage Limits"
 description:
-  Set hierarchical spending, token, and request limits at the gateway, team, and
-  app levels, with warning thresholds and quota fallbacks.
+  Set spending, token, and request budgets at the gateway, team, and app levels,
+  and give every metadata value its own separate budget using expression rules.
 ---
 
 The Zuplo AI Gateway provides hierarchical usage limits and budget controls to
@@ -13,7 +13,8 @@ gateway, team, and app levels.
 ## Budget Hierarchy
 
 Limits at every level apply together—a request is blocked when _any_ level's
-limit is exceeded, and the error names the level that blocked it:
+limit is exceeded, and the error names whether the whole application or the
+caller's own segment ran out:
 
 - **Gateway** - Limits across the Zuplo project (for example, $1,000/day),
   covering all teams and apps combined
@@ -24,28 +25,66 @@ limit is exceeded, and the error names the level that blocked it:
 
 ## Where limits are configured
 
-| Level   | Where                                                                             |
-| ------- | --------------------------------------------------------------------------------- |
-| Gateway | **Settings → Usage Limits**                                                       |
-| Team    | The team's **Usage & Limits** tab                                                 |
-| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) |
+| Level   | Where                                                                             | Per-metadata budgets |
+| ------- | --------------------------------------------------------------------------------- | -------------------- |
+| Gateway | **Settings → Usage Limits**                                                       | No                   |
+| Team    | The team's **Usage & Limits** tab                                                 | No                   |
+| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) | Yes                  |
 
-Each level supports the same three meters, each with independent daily and
-monthly settings:
+Gateway and team limits are inherited: they apply to every app beneath them,
+whether or not the app's chain includes Budgets and Costs. An app's own limits
+live on that policy, which is also the only place you can budget per metadata
+value.
 
-- **Budget** - spend in dollars
-- **Tokens** - input plus output tokens
-- **Requests** - request count
+:::note
+
+A team's **Policy Template** tab also carries a **Budgets and Costs** policy.
+That template seeds the policy chain of apps created in the team—it sets those
+apps' limits, not the team's own. Use **Usage & Limits** to cap the team.
+
+:::
+
+## How a budget rule works
+
+An app's budgets are a list of rules on the **Budgets and Costs** policy. Each
+rule answers two questions—what it budgets, and what the caps are.
+
+**Scope** decides who shares the budget:
+
+| Scope           | What it budgets                                             |
+| --------------- | ----------------------------------------------------------- |
+| **This app**    | One shared budget for all of the app's traffic              |
+| **By metadata** | A separate budget for every distinct value of an expression |
+
+A **By metadata** rule gives each caller its own allowance. With the expression
+`request.headers.get("x-user")` and a $5 daily cap, every distinct `x-user`
+value gets its own $5 per day—one user exhausting their budget doesn't affect
+anyone else. An app has a single shared budget, and can add several metadata
+rules alongside it.
+
+**Limit rows** set the caps. Each row is a meter, a period, an amount, and an
+action:
+
+| Field      | Values                                                            |
+| ---------- | ----------------------------------------------------------------- |
+| **Meter**  | Cost (dollars), Tokens (input plus output), Requests              |
+| **Period** | Hourly, Daily, Weekly, Monthly                                    |
+| **Limit**  | An absolute amount in the meter's own unit                        |
+| **Action** | **Block** rejects the request; **Warn** notifies without blocking |
+
+Add as many rows as you need to cap several meters and periods at once. A Warn
+row and a Block row on the same meter and period give you warn-then-block—warn
+at $80, block at $100. The warn amount has to be the lower of the two.
 
-For each meter and period you can set a **Limit** (usage at or above it gets
-blocked) and a **Warning** threshold (a percentage of the limit that triggers a
-warning notification without blocking). Leave a field empty to not enforce it.
+The **Overview** tab charts daily and monthly usage only. Hourly and weekly rows
+are enforced, but no meter on that tab tracks them.
 
 :::note
 
-Daily and monthly periods are anchored to your gateway, not the calendar: a
-daily period rolls over at the time of day (UTC) the gateway was created, and a
-monthly period runs anchor-day to anchor-day. Changing a limit mid-period
+Periods are anchored to your gateway, not the calendar. Every period rolls over
+relative to the time (UTC) the gateway was created, so a daily period resets at
+that hour rather than at midnight, and a monthly one on that day of the month.
+Teams and apps created later use the same anchor. Changing a limit mid-period
 doesn't reset the period's usage.
 
 :::
@@ -60,43 +99,102 @@ doesn't reset the period's usage.
 1. On the **Policies** tab, configure the **Budgets and Costs** policy (add it
    from **Add Policy** if the chain doesn't have it).
 
-1. Set daily or monthly limits for budget, tokens, or requests, and optional
-   warning thresholds.
+1. Select **Add rule**, choose the scope, and use **Add limit** to add rows for
+   the meters and periods you want to cap. For a **By metadata** rule, enter the
+   expression that identifies each caller.
 
-1. Save. The change applies within about a minute.
+1. Select **Apply**, then **Save changes** on the policy chain. The change
+   applies within about a minute.
 
 </Stepper>
 
-:::note
+Rules set on a parent team or on the gateway appear in the editor under
+**Inherited**. Edit those where they were created.
 
-Each period in the Budgets and Costs policy's options carries an `enabled` flag
-next to its number, and so does each warning threshold. A period enforces
-nothing until `enabled` is `true` _and_ `limit` is set—options that set only
-`limit` are silently inert. Watch for this when editing the policy's options
-directly, such as in `config/policies.json` or a
-[policy template](./policy-templates.mdx).
+### Budget expressions
 
-:::
+A **By metadata** rule identifies each caller with an expression evaluated per
+request. The editor validates it as you type. Available values include:
 
-If the app has a **quota fallback** model configured, an exceeded limit routes
-requests to that model instead of blocking with a `429`—see
-[Fallback Models](./fallback.mdx). The fallback's usage still counts toward the
-limits.
+- `request.headers.get("x-user")` and other request headers
+- `request.user.sub` and `request.user.data.<key>` from the authenticated API
+  key
+- `request.url`, `request.method`, `request.query`, `request.searchParams`, and
+  `request.params`
+- `context.contextId`, `context.requestId`, `context.route`, and
+  `context.custom`
 
-:::note{title="App, team, and gateway limits are configured separately"}
+The editor labels each expression by where its value comes from, because that
+decides how much the budget can be trusted. A **client-supplied** value—a header
+or query parameter—is attribution, not enforcement: a caller who changes it gets
+a fresh budget. Budget on `request.user.*`, labeled **verified**, when the
+segment itself has to hold, and keep a shared-budget rule alongside it as the
+hard cap.
 
-The Budgets and Costs policy configures and enforces an app's own limits. Team
-and gateway limits apply to every app automatically, whether or not the app's
-policy chain includes Budgets and Costs.
+:::caution
+
+Changing an expression starts a new budget. The old rule's usage stays with the
+old expression, so every value's accounting restarts from zero. Expressions are
+also case-sensitive: `get("X-User")` and `get("x-user")` read the same header
+but budget separately.
 
 :::
 
+To write rules by hand in `config/policies.json` or a
+[policy template](./policy-templates.mdx), see the
+[Budgets and Costs policy reference](../policies/ai-gateway-metering-v2-inbound.mdx).
+
+## Setting team and gateway limits
+
+Team and gateway limits cover everything beneath them, and apply to every app
+whether or not its chain includes Budgets and Costs.
+
+Both use the same editor as an app, with the same limit rows—meter, period,
+amount, and action. Open the team's **Usage & Limits** tab, or **Settings →
+Usage Limits** for the gateway, then **Add rule** and **Add limit**.
+
+Each level takes one shared budget covering everything beneath it: a team's caps
+all of its apps combined, and the gateway's caps the whole project. Rules set
+higher up appear under **Inherited**—edit those where they were created.
+
+## When a limit is exceeded
+
+If the app has a **quota fallback** model configured, an exceeded limit routes
+requests to that model instead of blocking—see
+[Fallback Models](./fallback.mdx), where the fallback model is selected. This
+applies to gateway and team limits as well as the app's own. The fallback's
+usage still counts toward the limits.
+
+Without a fallback, the request is rejected with `429 Too Many Requests` and a
+`budget` object naming what ran out:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/429",
+  "title": "Too Many Requests",
+  "detail": "Your daily cost budget has been exhausted (limit: 5).",
+  "budget": {
+    "scope": "dimension",
+    "dimensionedBy": "request.headers.get(\"x-user\")",
+    "ruleId": "3f2a9c1b",
+    "meter": "cost",
+    "window": "daily",
+    "limit": 5
+  }
+}
+```
+
+The `scope` tells the caller which budget they hit: `application` when a shared
+budget ran out, or `dimension` when their own segment did—two situations with
+different remedies. Quote the `ruleId` when raising a support request.
+
 :::caution{title="Budgets fail open by default"}
 
-The Budgets and Costs policy's `throwOnFailure` option controls how an error
-while checking the app's own limits is handled. It defaults to `false`, so the
-request continues through the gateway. Set it to `true` to reject the request
-instead. Team and gateway limit checks run independently of this policy.
+The Budgets and Costs policy's `throwOnFailure` option—**Fail closed when
+metering is unavailable** in the editor—controls how an error while checking the
+app's own limits is handled. It defaults to `false`, so the request continues
+through the gateway. Set it to `true` to reject the request instead. Team and
+gateway limit checks run independently of this policy.
 
 :::
 

package/docs/ai-gateway/vertex-ai.mdx

@@ -0,0 +1,389 @@
+---
+title: Using Vertex AI
+sidebar_label: Vertex AI
+description:
+  Serve Gemini and Model Garden models from your own Google Cloud project
+  through one provider configuration—one Vertex AI location, one project ID, and
+  one service account key. The gateway mints and refreshes the access tokens
+  Vertex requires.
+---
+
+**Vertex AI** is Google Cloud's managed model platform. Adding it as a provider
+serves both the Gemini family and Vertex's Model Garden partner models—DeepSeek,
+Qwen, GLM, Kimi, MiniMax, Gemma, and GPT-OSS—to your [apps](./apps.mdx) through
+the [Universal API](./universal-api.mdx), running on your Google Cloud project
+and your Google Cloud billing.
+
+Chat completions go to Vertex's **OpenAI-compatible endpoint**, so the gateway
+forwards OpenAI-shaped requests without translating them. Embeddings work too,
+though Vertex has no OpenAI-compatible embeddings endpoint—the gateway
+translates those onto Vertex's own embedding APIs, which is invisible from your
+app. What sets this provider apart is how you connect it: the endpoint is
+per-location, the Google Cloud project is a separate setting, and the credential
+is a **service account key file**—not an API key.
+
+:::caution{title="Vertex AI doesn't accept API keys"}
+
+Every other AI Gateway provider takes an API key. Vertex doesn't: its prediction
+endpoints reject API keys outright, answering that they expect an OAuth2 access
+token instead. The provider dialog asks for the JSON key file of a Google Cloud
+service account, and the gateway exchanges it for short-lived access tokens on
+your behalf. Pasting an API key into the field fails validation before the
+provider is saved.
+
+:::
+
+## Model references include the publisher prefix
+
+Apps reference a provider's models as `providerName/model`. Every Vertex model
+ID is publisher-qualified, so a Vertex model reference has two slashes in it:
+
+```
+vertexai/google/gemini-3.7-flash
+└──┬───┘ └──────────┬──────────┘
+provider          model
+```
+
+Everything before the **first** slash is the provider name you chose, and
+everything after it is the model ID exactly as Vertex expects it. The publisher
+isn't always `google`—Model Garden models carry their own vendor's prefix. A
+provider named `vertexai` serves all of these:
+
+- `vertexai/google/gemini-3.7-flash`
+- `vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`
+- `vertexai/deepseek-ai/deepseek-v3.2-maas`
+- `vertexai/zai-org/glm-5-maas`
+
+Copy model IDs from the model picker rather than typing them—the `-maas` suffix
+and the publisher prefix are both part of the ID.
+
+## How the gateway calls Vertex AI
+
+When no valid cached token exists, the gateway uses the service account key to
+request a short-lived Google OAuth 2.0 access token. It caches and refreshes
+that token, then calls Vertex's OpenAI-compatible endpoint with the token as the
+bearer credential.
+
+<Diagram height="h-64">
+  <DiagramNode id="app">Your app</DiagramNode>
+  <DiagramNode id="gateway" variant="zuplo">
+    AI Gateway
+  </DiagramNode>
+  <DiagramNode id="oauth" variant="orange">
+    Google OAuth
+  </DiagramNode>
+  <DiagramGroup id="gcp" label="Your Google Cloud project">
+    <DiagramNode id="compat" variant="blue">
+      OpenAI-compatible endpoint
+    </DiagramNode>
+    <DiagramNode id="embed" variant="green">
+      Vertex embedding APIs
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="app" to="gateway" label="Universal API" />
+  <DiagramEdge
+    from="gateway"
+    to="oauth"
+    label="service account key → access token"
+    lineStyle="dashed"
+  />
+  <DiagramEdge from="gateway" to="compat" label="chat completions" />
+  <DiagramEdge from="gateway" to="embed" label="embeddings" />
+</Diagram>
+
+The request URL the gateway builds combines both settings you enter:
+
+```
+https://us-central1-aiplatform.googleapis.com
+  /v1/projects/my-project-123/locations/us-central1/endpoints/openapi/chat/completions
+```
+
+The **location** lives in the hostname, which is why the provider dialog asks
+for a location instead of an endpoint URL. The **project** doesn't appear in the
+hostname at all—it appears only in the path—so it can't be derived from the
+endpoint and is a field of its own. That's why the project is required rather
+than optional: without it the gateway would have to guess, and a guess would
+send your traffic and your spend to someone else's Google Cloud project.
+
+## Supported endpoints
+
+| Endpoint               | Vertex AI models |
+| ---------------------- | ---------------- |
+| `/v1/chat/completions` | ✅ Forwarded     |
+| `/v1/embeddings`       | ✅ Translated    |
+| `/v1/responses`        | ❌               |
+| `/v1/messages`         | ❌               |
+
+Streaming (`stream: true`) works on chat completions.
+
+The gateway rejects `/v1/responses` and `/v1/messages` requests for Vertex
+models with a `400` error before any upstream call, because Vertex serves
+neither the OpenAI Responses API nor the Anthropic Messages API.
+
+:::note{title="Anthropic models on Vertex aren't supported"}
+
+Vertex also hosts Anthropic's Claude models, but on a different API surface than
+the one this provider uses. The gateway can't route to them. To use Claude
+models, add the [Anthropic](./providers.mdx) provider or
+[Bedrock Mantle](./bedrock-mantle.mdx).
+
+:::
+
+## Model availability depends on the location
+
+Google registers each Vertex model in specific locations, and it changes that
+list over time. Most Model Garden models are served only from the **global**
+location; the Gemini models are more widely available.
+
+The model picker doesn't filter by your provider's location, so every model
+stays selectable from every provider. If you call a model that isn't served
+where your provider points, Vertex answers with a `400` that names both:
+
+```
+Publisher model 'publishers/qwen/models/qwen3-coder-480b-a35b-instruct-maas'
+is not available in region 'us-central1'
+```
+
+Set the provider's **Location** to `global` if you plan to use Model Garden
+models, or add a second Vertex provider for a specific region and route to
+whichever one serves the model you want.
+
+## Before you begin
+
+You need:
+
+- A Google Cloud project with the **Vertex AI API**
+  (`aiplatform.googleapis.com`) enabled and billing enabled. Gemini models
+  require both.
+- A service account in that project holding the **Vertex AI User**
+  (`roles/aiplatform.user`) role, and a **JSON key** for it. The steps are in
+  [Set up Google Cloud](#set-up-google-cloud).
+- The project's **project ID**—the readable identifier such as `my-project-123`,
+  not the numeric project number.
+- An AI Gateway project in the Zuplo Portal.
+- An AI Gateway [app](./apps.mdx) to call the models from. The app page shows
+  the app's API URL, and its API key lives on the app's **API Key** tab.
+
+## Set up Google Cloud
+
+Do this before adding the provider—the key file you download in the last step is
+what the provider dialog asks for.
+
+<Stepper>
+
+1. In the [Google Cloud console](https://console.cloud.google.com/), select the
+   project you want to serve models from and note its **project ID**. The
+   console shows the ID next to the project name, alongside the project number;
+   the gateway needs the ID.
+
+1. Enable the **Vertex AI API** on the project, under **APIs & Services →
+   Library**. Confirm billing is enabled for the project as well.
+
+1. Create a service account under **IAM & Admin → Service Accounts**.
+
+1. Grant that service account the **Vertex AI User** (`roles/aiplatform.user`)
+   role **on the same project**. This is the smallest role that can call
+   prediction endpoints. Vertex AI Administrator grants more than the gateway
+   needs, and Vertex AI Viewer can't make predictions at all.
+
+1. Create a JSON key for the service account: open the service account, go to
+   **Keys → Add key → Create new key**, choose **JSON**, and download the file.
+   Keep it somewhere safe—Google doesn't let you download it again.
+
+</Stepper>
+
+:::note
+
+Enabling the API and granting the role are separate steps, and missing the first
+one is the most common setup failure. It surfaces as a `403` that talks about
+the Vertex AI API rather than about permissions, which reads like a bad key.
+
+:::
+
+## Add the provider
+
+Adding or editing providers requires the **Edit** permission, granted to Zuplo
+account and project **Admins**—see
+[Managing Providers](./managing-providers.mdx).
+
+<Stepper>
+
+1. Open
+   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
+   in your AI Gateway project in the Zuplo Portal.
+
+1. Click the **Add Provider** button.
+
+1. In the **AI Provider** list, select **Vertex AI** from the Default Providers
+   group.
+
+1. Review the **Provider Name**, which fills in as `vertexai` (a second
+   configuration becomes `vertexai-2`). You can replace it with your own name,
+   but only now—the name is permanent after creation, and it's the prefix in
+   every model reference: a provider named `vertexai` serves
+   `vertexai/google/gemini-3.7-flash`.
+
+1. In **Location**, enter the Vertex AI location to call, such as `us-central1`
+   or `europe-west4`. Enter `global` to use Vertex's global endpoint. The
+   gateway derives the endpoint from this value—there's no URL to enter.
+
+1. In **Google Cloud Project ID**, enter the project ID you noted earlier, such
+   as `my-project-123`. The dialog rejects an all-digits value, which is the
+   project number rather than the ID.
+
+1. In **Service Account Key (JSON)**, paste the entire contents of the JSON key
+   file you downloaded. Paste it whole—a truncated copy fails validation.
+
+1. Select the models to enable, or click **Select All**. The picker shows
+   Google's per-token prices, which the gateway uses to track cost per app. You
+   can change the selection later.
+
+1. Click **Create**.
+
+</Stepper>
+
+:::note
+
+Saving provider settings triggers an automatic production deployment of your
+gateway, because provider credentials are part of the deployed gateway. The
+change is live once the deployment completes.
+
+:::
+
+:::note{title="Prices in the picker are a snapshot"}
+
+The per-token prices shown in the model picker are recorded rates, not a live
+read of Google's price list, and some Gemini models are on promotional rates
+that Google marks as temporary. Treat the gateway's cost figures as an estimate
+and your Google Cloud bill as the record.
+
+:::
+
+When you edit the provider later—see
+[Managing Providers](./managing-providers.mdx)—the **Location** and **Google
+Cloud Project ID** fields show the saved values and stay editable, and you can
+replace the key file. Leave the key field blank to keep the stored key. The
+**Provider Name** doesn't change.
+
+## Verify the provider
+
+Once the deployment completes, send a chat completions request to your app's
+[Universal API](./universal-api.mdx) URL—shown at the top of the
+[app page](./apps.mdx)—with the app's API key as the bearer token and one of the
+models you enabled:
+
+```bash
+curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
+  -H "Authorization: Bearer $ZUPLO_APP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "vertexai/google/gemini-3.7-flash",
+    "messages": [{ "role": "user", "content": "Say hi" }]
+  }'
+```
+
+The URL is a sample—replace it with your app's API URL plus
+`/v1/chat/completions`, set `ZUPLO_APP_API_KEY` to the app's API key, and
+substitute any model you enabled for `vertexai/google/gemini-3.7-flash`.
+
+A `200` response confirms the provider works; the body carries
+`"provider": "vertex-ai"`—the provider type, not the name you chose. If the
+request fails immediately after you save the provider, the deployment may not
+have finished—retry before debugging further.
+
+## Call the models
+
+Use any OpenAI client with your app's URL plus `/v1` as the base URL and the
+app's API key:
+
+```ts
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.ZUPLO_APP_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+});
+
+const response = await client.chat.completions.create({
+  model: "vertexai/google/gemini-3.7-flash",
+  messages: [{ role: "user", content: "Summarize this ticket." }],
+});
+```
+
+Streaming works the same way—set `stream: true` and read the
+`chat.completion.chunk` events.
+
+### Embeddings
+
+Embeddings use the same client and the same `/v1/embeddings` endpoint as any
+other provider:
+
+```ts
+const embeddings = await client.embeddings.create({
+  model: "vertexai/google/gemini-embedding-2",
+  input: ["first document", "second document"],
+});
+```
+
+`dimensions` and `encoding_format` both work. Two Vertex-specific limits apply,
+and the gateway enforces both before calling Vertex, so you get a `400` rather
+than a partial charge:
+
+- **At most 250 inputs per request.** Split larger batches yourself.
+- **Text input only.** Pre-tokenized input—arrays of token IDs, which the OpenAI
+  API also accepts—is rejected, because Vertex has no way to represent it. Send
+  the original text.
+
+## Troubleshooting
+
+**The dialog rejects your credential.** Vertex uses a service account, not an
+API key. The field takes the whole JSON key file downloaded from **IAM & Admin →
+Service Accounts → Keys**. The dialog also rejects a workload identity
+federation configuration—its `type` is `external_account` rather than
+`service_account`—and a file whose `private_key` isn't a PEM-encoded key. Paste
+the file exactly as downloaded, keeping the `\n` escapes intact.
+
+**The dialog rejects your project ID.** Project IDs are 6 to 30 characters:
+lowercase letters, digits, and hyphens, starting with a letter and not ending in
+one. An all-digits value is the project number, which the Google Cloud console
+shows next to the ID; the gateway needs the ID.
+
+**A request fails with a `403` about the Vertex AI API.** The API isn't enabled
+on the project. Enable **Vertex AI API** under **APIs & Services → Library** and
+confirm the project has billing enabled. This error names the API rather than
+permissions, so it's easy to mistake for a credential problem.
+
+**A request fails with a permission error.** The service account is missing the
+**Vertex AI User** (`roles/aiplatform.user`) role, or holds it on a different
+project than the one configured on the provider. Grant the role on the same
+project you entered as the **Google Cloud Project ID**.
+
+**A request fails with `400` saying the model isn't available in the region.**
+The model isn't served from your provider's location. Most Model Garden models
+are global-only—see
+[Model availability](#model-availability-depends-on-the-location). Set the
+provider's **Location** to `global`, or use a provider that points at a location
+serving that model.
+
+**An embeddings request fails with `400` about the input.** The gateway accepts
+at most 250 inputs per request and text input only. See
+[Embeddings](#embeddings).
+
+**A `/v1/responses` or `/v1/messages` request fails with `400`.** Vertex's
+OpenAI-compatible endpoint serves neither API. Use `/v1/chat/completions`, or
+another provider for those endpoints—see
+[Supported endpoints](#supported-endpoints).
+
+## Next steps
+
+- [AI Providers](./providers.mdx)—the capability matrix across every supported
+  provider.
+- [Universal API](./universal-api.mdx)—the endpoints every app serves and how
+  model references work.
+- [Managing Providers](./managing-providers.mdx)—edit models, keys, the
+  location, and the project, and understand when changes deploy.
+- [AI Gateway Apps](./apps.mdx)—create the apps that call your Vertex-backed
+  models.
+- [Model Filtering policy](../policies/ai-gateway-model-filtering-v2-inbound.mdx)—control
+  which models each app can call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.2",
+  "version": "7.6.4",
   "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.2",
-    "@zuplo/core": "7.6.2",
-    "@zuplo/runtime": "7.6.2",
-    "@zuplo/test": "7.6.2"
+    "@zuplo/cli": "7.6.4",
+    "@zuplo/core": "7.6.4",
+    "@zuplo/runtime": "7.6.4",
+    "@zuplo/test": "7.6.4"
   }
 }