zuplo 7.7.10 → 7.7.12

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -70,9 +70,9 @@ settings file:
 - **Global:** `~/.claude/settings.json`
 - **Project-specific:** `.claude/settings.json` in your project directory
 
-Each approach below shows the `env` block to add to that file. Restart Claude
-Code after saving it, and all your Claude Code LLM requests route through the AI
-Gateway.
+Each approach below shows the `env` and `modelOverrides` blocks to add to that
+file. Restart Claude Code after saving it, and all your Claude Code LLM requests
+route through the AI Gateway.
 
 :::note
 
@@ -87,7 +87,7 @@ With this approach the gateway calls Anthropic with the API key you saved on the
 [provider](../managing-providers.mdx). Claude Code presents only the app's API
 key, and Anthropic bills the account that owns the provider key.
 
-Add the following environment configuration to the settings file:
+Add the following configuration to the settings file:
 
 ```json
 {
@@ -99,7 +99,13 @@ Add the following environment configuration to the settings file:
     "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
     "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
     "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
-    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5"
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5-1"
+  },
+  "modelOverrides": {
+    "claude-opus-5": "anthropic/claude-opus-5",
+    "claude-sonnet-5": "anthropic/claude-sonnet-5",
+    "claude-haiku-4-5-20251001": "anthropic/claude-haiku-4-5-20251001",
+    "claude-fable-5-1": "anthropic/claude-fable-5-1"
   }
 }
 ```
@@ -183,7 +189,7 @@ from Claude Code instead, as described below.
 
 ### Configure Claude Code
 
-Add the following environment configuration to the settings file. Don't set
+Add the following configuration to the settings file. Don't set
 `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` here or in your shell: either one
 replaces your `claude.ai` login, and the gateway would then forward that value
 to Anthropic as the credential.
@@ -198,7 +204,13 @@ to Anthropic as the credential.
     "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
     "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
     "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
-    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5"
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5-1"
+  },
+  "modelOverrides": {
+    "claude-opus-5": "anthropic/claude-opus-5",
+    "claude-sonnet-5": "anthropic/claude-sonnet-5",
+    "claude-haiku-4-5-20251001": "anthropic/claude-haiku-4-5-20251001",
+    "claude-fable-5-1": "anthropic/claude-fable-5-1"
   }
 }
 ```
@@ -246,23 +258,27 @@ it currently serves, and use those ids.
 None of Claude Code's built-in model names carry a provider prefix, so each of
 the model variables above must be set to a prefixed reference:
 
-- `ANTHROPIC_MODEL` — the main model. Required: without it Claude Code sends its
-  built-in default model unprefixed and the first request fails.
+- `ANTHROPIC_MODEL` — the startup model. Set it to a prefixed reference so the
+  gateway can route the first request.
 - `ANTHROPIC_SMALL_FAST_MODEL` — the model for background tasks.
 - `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
   `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` — what the
   `opus`/`sonnet`/`haiku`/`fable` aliases resolve to, so `claude --model opus`
   and `/model sonnet` keep working. In these examples,
-  `ANTHROPIC_DEFAULT_FABLE_MODEL` maps `fable` to `anthropic/claude-fable-5`.
+  `ANTHROPIC_DEFAULT_FABLE_MODEL` maps `fable` to `anthropic/claude-fable-5-1`.
+
+Claude Code's `/model` picker can select either an alias or an exact model ID.
+`ANTHROPIC_DEFAULT_*_MODEL` maps aliases to gateway model names;
+[`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
+maps exact IDs. The examples configure both so either selection works through
+the gateway.
 
 :::caution{title='HTTP 400: model must use "providerName/model"'}
 
-If Claude Code fails immediately with
-`The request body model must use "providerName/model"`, the request carried a
-model name without a provider prefix. The tier alias variables
-(`ANTHROPIC_DEFAULT_*_MODEL`) alone don't prevent this — they don't cover Claude
-Code's built-in default model. Always set `ANTHROPIC_MODEL` to a prefixed model
-reference.
+This error means the selected model lacks its provider prefix. At startup, check
+`ANTHROPIC_MODEL`. After choosing a picker entry, check its `modelOverrides`
+entry, or type `/model fable` to use the configured alias. Restart Claude Code
+after editing the settings file.
 
 :::
 

package/docs/ai-gateway/integrations/github-copilot.mdx

@@ -0,0 +1,165 @@
+---
+title: GitHub Copilot
+sidebar_label: GitHub Copilot
+description:
+  Route GitHub Copilot in VS Code and the Copilot CLI through an AI Gateway app
+  so the gateway authenticates, meters, and routes every Copilot model request.
+---
+
+[GitHub Copilot](https://github.com/features/copilot) can use your own model
+endpoint instead of GitHub's hosted models — the
+[Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)
+through environment variables, and VS Code through its
+[Custom Endpoint provider](https://code.visualstudio.com/docs/agent-customization/language-models#_add-a-custom-endpoint-model).
+Point that endpoint at an AI Gateway app, and every Copilot chat and agent
+request is authenticated with the app's key, metered against the app's budgets,
+and limited to the models you allow. Developers keep using Copilot exactly as
+before; the app's page in the Zuplo Portal shows their requests, tokens, and
+spend as they work.
+
+## Before you start
+
+<Stepper>
+
+1. Create a [provider](../managing-providers.mdx) for the models Copilot will
+   use, such as OpenAI or Anthropic
+
+2. [Create a team](../managing-teams.mdx) for the developers using Copilot
+
+3. Create an [app](../managing-apps.mdx) for Copilot and assign it to the team
+
+4. Copy the **API URL** and **API Key** shown at the top of the app page
+
+</Stepper>
+
+The gateway names models as `providerName/model`, where `providerName` is the
+name you gave the provider. The examples below use `openai` and `anthropic`;
+substitute your own provider names.
+
+## Copilot CLI
+
+The CLI reads its provider from four environment variables. Set the base URL to
+the app's API URL plus `/v1`, and name a model that supports tool calls, such as
+GPT-4.1:
+
+```bash
+export COPILOT_PROVIDER_BASE_URL="https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
+export COPILOT_PROVIDER_API_KEY="<your-ai-gateway-app-api-key>"
+export COPILOT_PROVIDER_TYPE="openai"
+export COPILOT_MODEL="openai/gpt-4.1-mini"
+```
+
+Start `copilot` from the same shell. Every request in the session now passes
+through the gateway.
+
+For a Claude model, use the `anthropic` provider type with the app's API URL
+without `/v1` — the CLI appends `/v1/messages` itself — and pass the key as a
+bearer token, which is the header the gateway reads:
+
+```bash
+export COPILOT_PROVIDER_BASE_URL="https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e"
+export COPILOT_PROVIDER_BEARER_TOKEN="<your-ai-gateway-app-api-key>"
+export COPILOT_PROVIDER_TYPE="anthropic"
+export COPILOT_MODEL="anthropic/claude-sonnet-4-6"
+```
+
+The CLI speaks Chat Completions and the Messages API and sets a `temperature` on
+every request. GPT-4.1, GPT-4o, Claude Sonnet 4.6, and Claude Haiku 4.5 all
+accept that; OpenAI's GPT-5.x reasoning models and Claude Sonnet 5 don't, so use
+them from VS Code instead.
+
+## VS Code
+
+Add the gateway as a Custom Endpoint provider, then describe your models in the
+configuration file VS Code opens.
+
+<Stepper>
+
+1. Run **Chat: Manage Language Models** from the Command Palette
+
+2. Select **Add Models**, then **Custom Endpoint**
+
+3. Enter a name for the group, such as `Zuplo AI Gateway`, and paste the app's
+   API key
+
+4. Select **Chat Completions** as the API type
+
+5. Replace the `models` array in the `chatLanguageModels.json` file that opens
+   with the models you want in the picker
+
+</Stepper>
+
+This configuration offers a GPT model and a Claude model from one app:
+
+```json
+[
+  {
+    "name": "Zuplo AI Gateway",
+    "vendor": "customendpoint",
+    "apiKey": "${input:chat.lm.secret.321f64a2}",
+    "models": [
+      {
+        "id": "openai/gpt-5.6",
+        "name": "GPT-5.6 (Zuplo)",
+        "apiType": "responses",
+        "url": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/responses",
+        "toolCalling": true,
+        "vision": true,
+        "maxInputTokens": 128000,
+        "maxOutputTokens": 16000,
+        "requestHeaders": { "Authorization": "Bearer ${apiKey}" }
+      },
+      {
+        "id": "anthropic/claude-sonnet-5",
+        "name": "Claude Sonnet 5 (Zuplo)",
+        "apiType": "messages",
+        "url": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/messages",
+        "toolCalling": true,
+        "vision": true,
+        "maxInputTokens": 200000,
+        "maxOutputTokens": 64000,
+        "requestHeaders": { "Authorization": "Bearer ${apiKey}" }
+      }
+    ]
+  }
+]
+```
+
+Three lines carry the integration:
+
+- **`apiKey`** is a reference to the key you pasted, which VS Code keeps in its
+  secret storage and reads at request time. Leave it as written; to change the
+  key, use **Chat: Manage Language Models**.
+- **`requestHeaders`** sends the key as `Authorization: Bearer <key>`, the
+  header the gateway's
+  [Authentication policy](../../policies/ai-gateway-auth-v2-inbound.mdx) reads.
+  VS Code's default header depends on the API type, so set it on every model.
+- **`apiType`** and the `url` path select the API the model speaks: `responses`
+  for OpenAI's reasoning models such as GPT-5.x, `messages` for Claude through
+  the gateway's native Messages passthrough, and `chat-completions` with a
+  `/v1/chat/completions` URL for other chat models. Set it on each model so
+  models with different APIs share one entry in the picker.
+
+Save the file and pick a model from the chat model picker.
+
+## What routes through the gateway
+
+Chat and agent requests, on both surfaces. Copilot's inline code completions
+stay on GitHub's infrastructure. The app's
+[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
+policy decides which models Copilot may use.
+
+## Troubleshooting
+
+Copilot reports gateway errors as a retry failure, such as
+`502 token expired or invalid: 401`. The gateway's own response is in the
+**GitHub Copilot Chat** channel of VS Code's Output panel, or in the CLI's error
+text.
+
+| The gateway responds                                              | Cause                                                                          | Fix                                                                     |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `401` `Header configured by options.authHeader is missing`        | The key was sent as `x-api-key`                                                | VS Code: add `requestHeaders`. CLI: use `COPILOT_PROVIDER_BEARER_TOKEN` |
+| `401` `Invalid Authorization Scheme`                              | VS Code's `apiKey` was replaced with the key itself, so the key sent was empty | Re-enter the key with **Chat: Manage Language Models**                  |
+| `404`                                                             | The `url` stops at the app ID                                                  | Append `/v1/responses`, `/v1/messages`, or `/v1/chat/completions`       |
+| `Function tools with reasoning_effort are not supported`          | A GPT-5.x model on Chat Completions                                            | VS Code: `"apiType": "responses"`. CLI: use a GPT-4.1 or Claude model   |
+| `'temperature' does not support 0` or `temperature is deprecated` | The CLI's temperature setting on a GPT-5.x or Claude Sonnet 5 model            | Use GPT-4.1, GPT-4o, Claude Sonnet 4.6, or Claude Haiku 4.5             |

package/docs/dedicated/advanced/host-header-override.mdx

@@ -0,0 +1,93 @@
+---
+title: "Managed Dedicated: Host Header Override"
+sidebar_label: Host Header Override
+---
+
+By default, the `Host` header your gateway sends to a backend is derived from
+the URL it connects to. Host header override lets your code send a `Host` header
+that differs from the hostname in the request URL, so the gateway can connect to
+one address while the backend sees the hostname it expects.
+
+This setting is only available on [Managed Dedicated](../overview.mdx) instances
+and is off by default.
+
+## When to use it
+
+Reach for this when the address you connect to and the hostname your backend
+expects aren't the same:
+
+- **Virtual-hosted backends.** A single load balancer, ingress controller, or
+  web server hosts several sites and picks one based on the `Host` header. Your
+  gateway connects to the shared address and names the site it wants.
+- **Private networking.** With
+  [private networking](../aws-private-networking.mdx), you reach a backend
+  through an internal endpoint or IP whose DNS name doesn't match the public
+  hostname the backend is configured for, such as `https://10.0.4.12` with a
+  `Host` of `api.acme.com`.
+- **Testing a new backend before DNS moves.** Point the gateway at the new
+  origin's address while sending the production `Host` header, so you can
+  validate the migration without changing public DNS.
+- **Legacy backends keyed on the hostname.** Applications that route, build
+  links, or select a tenant from the `Host` header keep working when the gateway
+  sits in front of them.
+
+:::caution
+
+An incorrect `Host` header can send traffic to the wrong site on a shared
+backend, and some applications trust the header when building redirects and
+links. Enable this setting only if you need it, and set the header to a value
+your code controls rather than one copied from client input.
+
+:::
+
+## Enable the setting
+
+Add `allowHostHeaderOverride` to the `zuplo.jsonc` file at the root of your
+project and deploy:
+
+```jsonc
+{
+  "version": 1,
+  "projectType": "managed-dedicated",
+  "allowHostHeaderOverride": true,
+}
+```
+
+The setting applies to the whole project. Without it, a `Host` header you set on
+an outbound request is ignored.
+
+:::note
+
+The `zuplo.jsonc` file isn't editable in the Zuplo Portal. Connect your project
+to [source control](../source-control.mdx) and edit the file there or push a
+local change with git. See
+[Project Configuration](../../programmable-api/zuplo-json.mdx) for the other
+settings this file supports.
+
+:::
+
+## Example
+
+Once the setting is enabled, set the `Host` header on any outbound request. This
+[custom handler](../../handlers/custom-handler.mdx) connects to an internal load
+balancer and tells it which site to serve:
+
+```ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const url = new URL(request.url);
+
+  return fetch(`${environment.INTERNAL_ORIGIN}${url.pathname}${url.search}`, {
+    method: request.method,
+    body: request.body,
+    headers: {
+      ...Object.fromEntries(request.headers),
+      Host: "api.acme.com",
+    },
+  });
+}
+```
+
+With `INTERNAL_ORIGIN` set to `https://10.0.4.12`, the gateway connects to
+`10.0.4.12` and the backend receives a request for `api.acme.com`.

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

@@ -355,34 +355,23 @@ have both actions, the `warn` value must be less than the `block` value. The
 policy does not treat entries whose `budgetBy` is `app` as expression budget
 rules.
 
-### Supported expressions
-
-Expressions read one string or safe integer from request-time data. Use these
-canonical forms when writing application configuration:
-
-| Source                      | Canonical expression example                |
-| --------------------------- | ------------------------------------------- |
-| Request URL or method       | `request.url`, `request.method`             |
-| One request header          | `request.headers.get("x-customer-id")`      |
-| Authenticated subject       | `request.user.sub`                          |
-| User data                   | `request.user.data.profile.organizationId`  |
-| Query parameter             | `request.query.customerId`                  |
-| Query parameter (map form)  | `request.searchParams.customerId`           |
-| Route parameter             | `request.params.productId`                  |
-| Custom context data         | `context.custom.account.id`                 |
-| Route data                  | `context.route.path`                        |
-| Incoming request data       | `context.incomingRequestProperties.country` |
-| Request or context identity | `request.user.sub`, `context.requestId`     |
-| A key requiring brackets    | `request.user.data["team-id"]`              |
-
-The `expression` field contains the complete expression. Do not wrap it in an
-interpolation marker such as `${...}`. Expressions use values from the request
-and context, including values set by earlier policies. Place policies that set
-these values before Semantic Cache. You can change an expression in the
+### Expressions
+
+An expression selects one value from the request or its context, such as
+`request.headers.get("x-user-id")` or `request.user.data["team-id"]`. Every
+distinct value gets its own budget.
+
+The expression grammar, the selectable properties, what a value must be, and
+what happens when an expression does not resolve are documented once, on the
+[AI Gateway Metering](/docs/policies/ai-gateway-metering-v2-inbound) policy
+page. The same grammar applies here.
+
+Two things are specific to application configuration. A policy that sets a value
+an expression reads must run before Semantic Cache, which can answer without
+reaching the rest of the chain. And you can change an expression in the
 application configuration without rebuilding or redeploying the gateway.
 
-JSON encoding and expression syntax are separate. When writing raw JSON, escape
-the double quotes required by a bracket segment:
+When writing raw JSON, escape the double quotes a bracket segment needs:
 
 ```json
 {
@@ -390,58 +379,14 @@ the double quotes required by a bracket segment:
 }
 ```
 
-After a JSON parser decodes this value, the expression is
+After a JSON parser decodes that value the expression is
 `request.user.data["team-id"]`; the backslashes are not part of its identity.
-Code that creates application configuration should build an ordinary string and
-let its JSON serializer handle the transport escaping:
+Code that builds application configuration should create an ordinary string and
+let its JSON serializer add the transport escaping.
 
-```ts
-const expression = 'request.user.data["team-id"]';
-const body = JSON.stringify({ expression });
-```
-
-Header expressions are terminal. Header names are case-insensitive; use
-lowercase in stored expressions. The parser accepts the canonical
-`request.headers.get("content-type")` form and the equivalent
-`request.headers.content-type` and `request.headers["content-type"]` forms. The
-canonical form keeps header access visually distinct from an ordinary object
-property.
-
-A dot property starts with an ASCII letter, `_`, or `$`, followed by those
-characters, ASCII digits, or hyphens. Canonical rendering uses quoted brackets
-for keys containing `$` or `-`, or any other non-identifier character. For
-example, `context.custom.team-id` is accepted and its canonical form is
-`context.custom["team-id"]`. Single- and double-quoted bracket properties are
-accepted. Whitespace immediately inside brackets is accepted but is not
-canonical.
-
-The selectable data model is:
-
-| Root      | Selectable properties                                                                                                                                                                                                                                           |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request` | `url`, `method`, `headers`, `user.sub`, `user.data`, `query`, `searchParams`, `params`, and the scalar Fetch request metadata `bodyUsed`, `cache`, `credentials`, `destination`, `integrity`, `keepalive`, `mode`, `redirect`, `referrer`, and `referrerPolicy` |
-| `context` | `contextId`, `requestId`, `custom`, `route`, and `incomingRequestProperties`                                                                                                                                                                                    |
-
-Expressions cannot read the request body, call logging or policy methods, or
-access properties outside this table.
-
-Expressions have these limits:
-
-- The expression is at most 1,024 UTF-8 bytes and contains well-formed Unicode.
-- Quoted keys are non-empty and do not contain double quotes, backslashes,
-  control characters, U+2028, or U+2029. String escapes are not supported.
-- Canonical expressions contain no syntax whitespace. Spaces inside a quoted key
-  are part of the key.
-- Wildcards, recursive descent, filters, numeric bracket indexes, calls other
-  than the terminal header `.get("name")`, function arguments, and roots other
-  than `request` and `context` are not supported. For example,
-  `request.url.substring(5, 1)` is not a supported expression.
-- Traversal reads own properties from plain objects and keys from declared Maps.
-  It does not traverse arrays, class instances, inherited properties, or the
-  property names `__proto__`, `constructor`, and `prototype`.
-
-An authentication policy can populate `request.user`. A custom policy earlier in
-the chain can derive a value and place it in a request header:
+An expression selects one value and cannot combine several. To budget by a
+composite value, compute it in a custom policy earlier in the chain and store it
+somewhere an expression can read:
 
 ```ts
 import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
@@ -463,19 +408,6 @@ The corresponding expression is `request.headers.get("x-budget-customer")`.
 Configuration code should create that ordinary string and pass the enclosing
 object to `JSON.stringify`; the serializer adds the JSON transport escaping.
 
-The expression chooses one value; it does not concatenate values, run
-JavaScript, or evaluate conditions. Compute composite values in an earlier
-policy and store the result in a supported request or context property.
-
-The selected value must be a string or a safe integer. The runtime converts the
-value to well-formed NFC Unicode and ignores it when it exceeds 256 UTF-8 bytes
-or contains control characters, U+2028, or U+2029. A missing or invalid value
-does not contribute to the rule for that request.
-
-Use consistent spelling for each expression. Different spellings, such as single
-quotes and double quotes, identify different budget rules even when they select
-the same value.
-
 Invalid budget rules and unsupported expressions are logged and skipped. Other
 valid rules continue to apply.
 

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

@@ -68,6 +68,162 @@ value of its expression. An action of `"warn"` notifies without blocking. An
 action of `"block"` activates the configured quota fallback or returns
 `429 Too Many Requests` when usage reaches the value.
 
+## Budget expressions
+
+A rule with `"budgetBy": "expression"` gives every distinct value of its
+expression its own budget. A daily cost budget of five dollars on
+`request.headers.get("x-user-id")` gives each user five dollars a day, rather
+than five dollars shared across all users.
+
+An expression selects one value from the request or its context. It is a
+selector, not code: there are no comparisons, arithmetic, string concatenation,
+or method calls other than the header accessor below.
+
+### Supported expressions
+
+| Expression                                 | Example                                     | Selects                                                         |
+| ------------------------------------------ | ------------------------------------------- | --------------------------------------------------------------- |
+| `request.headers.get("<name>")`            | `request.headers.get("x-user-id")`          | One request header. Header names are case-insensitive.          |
+| `request.query.<name>`                     | `request.query.tenant`                      | One query-string parameter.                                     |
+| `request.searchParams.<name>`              | `request.searchParams.tenant`               | One query-string parameter.                                     |
+| `request.params.<name>`                    | `request.params.customerId`                 | One path parameter from the matched route.                      |
+| `request.user.sub`                         | `request.user.sub`                          | The authenticated consumer's subject, such as the API key name. |
+| `request.user.data.<property>`             | `request.user.data.organizationId`          | A property of the consumer's metadata, including nested ones.   |
+| `request.<property>`                       | `request.method`                            | A scalar request property.                                      |
+| `context.custom.<property>`                | `context.custom.tenantId`                   | A value your own policies or handlers put on `context.custom`.  |
+| `context.route.<property>`                 | `context.route.path`                        | A property of the matched route, such as `path` or `label`.     |
+| `context.incomingRequestProperties.<name>` | `context.incomingRequestProperties.country` | A connection property, such as `country`, `city`, or `asn`.     |
+
+The selectable scalar request properties are `bodyUsed`, `cache`, `credentials`,
+`destination`, `integrity`, `keepalive`, `method`, `mode`, `redirect`,
+`referrer`, `referrerPolicy`, and `url`.
+
+Use quoted brackets for any key that is not a plain identifier:
+`request.query["team-id"]`, `context.custom["tenant.id"]`.
+
+`context.incomingRequestProperties` exposes connection data only: `country`,
+`city`, `region`, `regionCode`, `continent`, `colo`, `latitude`, `longitude`,
+`postalCode`, `metroCode`, `timezone`, `ip`, `asn`, `asOrganization`, and
+`httpProtocol`. Client-certificate and mTLS verification fields are not
+selectable. To budget per client certificate, run the mTLS Authentication policy
+first and select the metadata it attaches, such as
+`request.user.data.mtlsAuth.sha256Fingerprint`.
+
+An expression is limited to 1024 bytes and 32 property segments.
+
+### Examples
+
+Give every end user their own daily spend budget, keyed by a header your
+application sends:
+
+```json
+{
+  "budgetBy": "expression",
+  "expression": "request.headers.get(\"x-user-id\")",
+  "meters": [
+    { "meter": "cost", "period": "daily", "value": 5, "action": "block" }
+  ]
+}
+```
+
+Give every customer of yours their own monthly token budget, keyed by metadata
+on the API key that made the request:
+
+```json
+{
+  "budgetBy": "expression",
+  "expression": "request.user.data.organizationId",
+  "meters": [
+    {
+      "meter": "tokens",
+      "period": "monthly",
+      "value": 8000000,
+      "action": "warn"
+    },
+    {
+      "meter": "tokens",
+      "period": "monthly",
+      "value": 10000000,
+      "action": "block"
+    }
+  ]
+}
+```
+
+Cap requests per tenant per hour, keyed by a path parameter on a route such as
+`/tenants/:tenantId/chat`:
+
+```json
+{
+  "budgetBy": "expression",
+  "expression": "request.params.tenantId",
+  "meters": [
+    {
+      "meter": "requests",
+      "period": "hourly",
+      "value": 1000,
+      "action": "block"
+    }
+  ]
+}
+```
+
+### Values
+
+An expression must resolve to a string or a safe integer. The runtime converts
+the value to well-formed NFC Unicode, and ignores it when it exceeds 256 UTF-8
+bytes or contains control characters, U+2028, or U+2029. Values are
+case-sensitive, so `Acme` and `acme` get separate budgets, but two strings that
+normalize to the same NFC text share one budget.
+
+When an expression resolves to nothing, or to something else such as an object,
+an array, or a fractional number, that rule does not count or block the request.
+Other rules still apply. Pair a rule on a value you must enforce with a policy
+that rejects requests missing it, such as API key authentication or request
+validation.
+
+### Not supported
+
+| Not supported                                        | Use instead                                                         |
+| ---------------------------------------------------- | ------------------------------------------------------------------- |
+| Request body values, such as `request.body.userId`   | A header, a query parameter, a path parameter, or API key metadata. |
+| Whole objects, such as `request.headers`             | One value, such as `request.headers.get("x-user-id")`.              |
+| Comparisons, `&&`, ternaries, and literals           | One selector per rule. An application can have up to five rules.    |
+| String methods, such as `.toLowerCase()`             | The value as the client sends it.                                   |
+| Wildcards and multiple keys in one expression        | One rule per value you want to budget.                              |
+| Arrays, class instances, and inherited properties    | A plain value the gateway or your own policy sets.                  |
+| Per-request identifiers, such as `context.requestId` | A value shared by many requests, such as a user or tenant.          |
+
+An unsupported expression does not fail the request. The rule is skipped, and
+the request is not budgeted by it.
+
+### Keep the spelling stable
+
+Each expression is stored exactly as you write it, and its budgets are tracked
+under that exact text. `request.headers.get("x-user-id")` and
+`request.headers["x-user-id"]` read the same header but keep separate budgets,
+and editing a rule's expression starts its budgets over. Single quotes and
+double quotes likewise identify different rules. Use the spellings in the table
+above.
+
+Several forms parse, so prefer the canonical one. A header is written
+`request.headers.get("content-type")`, with a lowercase name; the equivalent
+`request.headers.content-type` and `request.headers["content-type"]` are
+accepted but keep separate budgets. A dot property starts with a letter, `_`, or
+`$`; a key containing anything else takes quoted brackets, so
+`context.custom.team-id` is canonically `context.custom["team-id"]`.
+
+In raw JSON, escape the double quotes a bracket segment needs:
+
+```json
+{
+  "expression": "request.user.data[\"team-id\"]"
+}
+```
+
+After a JSON parser decodes that value the expression is
+`request.user.data["team-id"]`; the backslashes are not part of its identity.
+
 ## Team limits
 
 Application budgets apply only to that application. Parent team and gateway

package/docs/policies/ai-gateway-metering-v2-inbound/intro.md

@@ -3,6 +3,10 @@ requests and enforces spend, token, and request budgets. When a limit is
 exceeded, it uses the model selection's quota fallback when one is configured or
 returns `429 Too Many Requests`.
 
+A budget rule covers the whole application, or gives every distinct value of an
+expression its own budget, such as one budget per user with
+`request.headers.get("x-user-id")`.
+
 Place it after Model Filtering and Fallback Model, and before policies such as
 Semantic Cache that may answer without calling a provider. Metering fails open
 by default when its service is unavailable; set `throwOnFailure` to `true` to

package/docs/policies/ai-gateway-metering-v2-inbound/schema.json

@@ -77,17 +77,19 @@
                 "properties": {
                   "budgetBy": {
                     "type": "string",
-                    "enum": ["app", "expression"]
+                    "enum": ["app", "expression"],
+                    "description": "Budget the application as a whole (\"app\"), or give every distinct value of an expression its own budget (\"expression\")."
                   },
                   "expression": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Required when budgetBy is \"expression\"; forbidden for \"app\". Each distinct value gets its own budget."
+                    "description": "Required when budgetBy is \"expression\"; forbidden for \"app\". Each distinct value gets its own budget. Select one value from the request or its context: request.headers.get(\"x-user-id\"), request.query.tenant, request.params.customerId, request.user.sub, request.user.data.organizationId, request.method, request.url, context.custom.tenantId, context.route.path, or context.incomingRequestProperties.country. Comparisons, arithmetic, string methods, and request body values are not supported."
                   },
                   "meters": {
                     "type": "array",
                     "minItems": 1,
                     "maxItems": 24,
+                    "description": "Thresholds this rule enforces. Add one entry per meter, period, and action you want.",
                     "items": {
                       "type": "object",
                       "additionalProperties": false,
@@ -95,19 +97,23 @@
                       "properties": {
                         "meter": {
                           "type": "string",
-                          "enum": ["cost", "requests", "tokens"]
+                          "enum": ["cost", "requests", "tokens"],
+                          "description": "What to measure: US dollars spent (\"cost\"), requests made (\"requests\"), or tokens used (\"tokens\")."
                         },
                         "period": {
                           "type": "string",
-                          "enum": ["hourly", "daily", "weekly", "monthly"]
+                          "enum": ["hourly", "daily", "weekly", "monthly"],
+                          "description": "How often usage resets."
                         },
                         "value": {
                           "type": "number",
-                          "exclusiveMinimum": 0
+                          "exclusiveMinimum": 0,
+                          "description": "The threshold for this meter and period. Cost is in US dollars."
                         },
                         "action": {
                           "type": "string",
-                          "enum": ["warn", "block"]
+                          "enum": ["warn", "block"],
+                          "description": "What happens at the threshold: \"warn\" notifies and lets the request through, \"block\" uses the configured quota fallback model or returns 429 Too Many Requests."
                         }
                       }
                     }

package/docs/programmable-api/zuplo-json.mdx

@@ -89,11 +89,14 @@ to `false`.
 
 Allow the Host header to be overridden by the client. This configuration
 defaults to `false`. This is only supported in managed dedicated environments.
-Only enable this setting if you understand the implications.
+Only enable this setting if you understand the implications. See
+[Host Header Override](../dedicated/advanced/host-header-override.mdx) for when
+to use it and an example.
 
 ```jsonc
 {
   "version": 1,
+  "projectType": "managed-dedicated",
   "allowHostHeaderOverride": true,
 }
 ```

package/docs/self-hosted/install.md

@@ -12,24 +12,22 @@ certificates from cert-manager. Before you begin, complete the
 Set these variables in the shell that you use for the installation:
 
 ```bash
-# From the Zuplo portal. See Requirements for instructions.
-export ZUPLO_ACCOUNT_NAME='acme-corp'
 
 # Provided by Zuplo during onboarding.
 export ZUPLO_CHART_VERSION='<chart version from onboarding>'
 export ZUPLO_REGISTRY_KEY='<base64 credential from onboarding>'
 
-# Yours.
-export ZUPLO_SUBDOMAIN='api.example.com'
-export ZUPLO_MANAGEMENT_HOSTNAME='zuplo-admin.example.com'
-export ZUPLO_BUILD_REGISTRY='us-docker.pkg.dev/acme-corp/zuplo-gateways'
-export ACME_EMAIL='platform@example.com'
+# Provided by you
+
+# These are the credentials to your gateway image registry.
+export BUILDER_REGISTRY_USER='your-example-registry-user'
+export BUILDER_REGISTRY_PASSWORD='your-example-registry-user-pw'
 ```
 
 ## Authenticate to the Zuplo registry
 
-The chart is an OCI artifact in Zuplo's registry. The same credential pulls the
-chart and the component images.
+The Zuplo Helm chart is an OCI artifact in Zuplo's registry. The same credential
+pulls the chart and the component images.
 
 ```bash
 printf '%s' "$ZUPLO_REGISTRY_KEY" |
@@ -52,7 +50,8 @@ account:
 
 deployments:
   # Parent domain for your APIs. Needs wildcard DNS:
-  #   *.api.example.com -> your ingress address
+  #   *.api.example.com -> your ingress address. For example, a preview
+  #  domain deployment might look like your-preview-branch-abs0ef.api.example.com.
   subdomain: api.example.com
 
 managementApi:
@@ -68,12 +67,11 @@ builder:
   secretName: builder-secret
 
 cert-manager:
-  # Issues and renews one certificate per deployment hostname. Leaving this on
-  # is what keeps a wildcard certificate out of the picture.
+  # cert-manager is used for managing the lifecyle of each deployment certificate.
   enabled: true
   acme:
-    # Required when cert-manager.enabled is true. The certificate authority
-    # sends expiration warnings to this address.
+    # Required when cert-manager.enabled is true. Used to register the ACME
+    # account with the certificate authority.
     email: platform@example.com
 ```
 
@@ -91,17 +89,25 @@ zuploImageRegistry:
   password: ${ZUPLO_REGISTRY_KEY}
 
 builder:
-  username: _json_key_base64
-  password: ${ZUPLO_REGISTRY_KEY}
+  username: ${BUILDER_REGISTRY_USER}
+  password: ${BUILDER_REGISTRY_PASSWORD}
 EOF
 ```
 
-:::danger{title="Treat this file as a secret"}
+:::danger{title="Protect registry credentials"}
+
+This file contains registry credentials. Add `zuplo-secrets.yaml` to
+`.gitignore` before creating it, restrict access to the file, and delete the
+local copy after installation. Keep the credentials in your organization's
+secret manager for future upgrades.
+
+For automated installations, generate the file from CI secrets or a secret
+manager. If you store the file in Git, encrypt it with a tool such as SOPS and
+decrypt it when running Helm.
 
-The chart doesn't support `existingSecret`. It stores these values in Kubernetes
-Secrets and in the Helm release history. Don't commit this file as plaintext.
-Encrypt it with SOPS or Sealed Secrets, or generate it in CI from a secret
-store. Add it to `.gitignore` with your kubeconfig.
+Helm stores these credentials in its release history, and the chart creates
+Kubernetes Secrets from them. Restrict access to these Secrets, including Helm's
+release Secrets.
 
 :::
 
@@ -139,7 +145,8 @@ namespaces:
 
 Without `--version`, Helm selects the most recent chart available at
 installation time. Record the pinned version with `zuplo-values.yaml` so that
-you can review and reproduce upgrades.
+you can review and reproduce upgrades. Your Zuplo solutions architect will tell
+you which version to install.
 
 :::
 
@@ -156,16 +163,52 @@ NAME                    TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)
 zuplo-haproxy-ingress   LoadBalancer   10.128.82.11   203.0.113.24     80:31670/TCP,443:31011/TCP   50s
 ```
 
-Create two DNS A records pointing at `EXTERNAL-IP`, both resolving publicly and
-neither behind a TLS-terminating proxy:
+Create two DNS A records pointing at EXTERNAL-IP, both resolving publicly:
 
 | Type | Name                      | Value          |
 | ---- | ------------------------- | -------------- |
 | `A`  | `*.api.example.com`       | `203.0.113.24` |
 | `A`  | `zuplo-admin.example.com` | `203.0.113.24` |
 
-Certificates can't be issued until these records resolve. cert-manager checks
-the challenge URL from inside the cluster before it contacts the certificate
-authority.
+Certificate issuance requires the HTTP-01 challenge URL at
+http://<hostname>/.well-known/acme-challenge/<token> to be reachable from inside
+the cluster and the public internet. If you use a proxy such as Cloudflare,
+configure it to forward these requests to the cluster without authentication or
+changes to the challenge response. cert-manager checks the URL before asking the
+certificate authority to validate the challenge.
 
-Next, [verify your installation](./verify.md).
+## Verify your installation
+
+Use the [Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor)
+to check the installation. Doctor is a CLI that reads your installation through
+your kubeconfig and probes its DNS, TLS, and HTTP endpoints. It checks the Helm
+release, the `Configuration` resource, Deployment health, ingress reachability,
+certificate issuance, DNS records, the management API, and the builder
+configuration. It reads the installation and doesn't change it.
+
+Download the archive for your machine from the
+[releases page](https://github.com/zuplo/self-hosted-doctor/releases), verify
+its checksum, extract it, and run the full suite against your current kubeconfig
+context:
+
+```bash
+./zuplo-self-hosted-doctor verify
+```
+
+Doctor exits `0` when no check failed, `1` when a check failed, and `3` when it
+couldn't run. Each warning and failure names a diagnostic step and links to the
+matching entry in [Troubleshooting](./troubleshooting.md).
+
+To also check authenticated access to the management API, set `ZUPLO_API_KEY` in
+your shell before running `verify`. Without a key, Doctor checks only that
+unauthenticated requests are rejected.
+
+The repository's README covers selecting individual checks, comparing a local
+values file, private certificate authorities, and JSON output.
+
+:::note
+
+Doctor doesn't deploy a project. To confirm the full build-and-serve path, run
+`npx zuplo deploy` against your account after Doctor passes.
+
+:::

package/docs/self-hosted/overview.md

@@ -184,10 +184,10 @@ images, and the credentials to pull them.
 ## Get started
 
 1. Review the [requirements](./requirements.md) and run the preflight checks.
-2. [Install](./install.md) the Helm chart.
-3. [Verify the installation](./verify.md), including a complete deployment.
-4. [Upgrade](./upgrade.md) to later chart versions when needed.
-5. Use [troubleshooting](./troubleshooting.md) to resolve installation and
+2. [Install](./install.md) the Helm chart, then verify the installation with the
+   [Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor) CLI.
+3. [Upgrade](./upgrade.md) to later chart versions when needed.
+4. Use [troubleshooting](./troubleshooting.md) to resolve installation and
    deployment errors.
 
 To discuss your specific requirements,

package/docs/self-hosted/requirements.md

@@ -105,11 +105,18 @@ For HTTP-01 validation, the certificate authority must also reach the ingress on
 port 80. If your cluster can't expose port 80 to the public internet, discuss an
 alternative certificate configuration with your Zuplo solutions architect.
 
-## Access to Zuplo services
-
-The cluster needs outbound HTTPS to Zuplo services, both container registries,
-and your certificate authority. The management API hostname is the only inbound
-path.
+The cluster also needs outbound access to:
+
+- Zuplo services for deployment configuration and management API authentication.
+- Zuplo's private container registry and the public registries used by the
+  chart's bundled components.
+- Your container registry to push and pull gateway images.
+- Docker Hub and Debian package repositories to build gateway images.
+- Your ACME certificate authority to issue and renew certificates.
+
+The Helm chart installs the required components, but the cluster downloads their
+container images and gateway build dependencies. If you restrict outbound
+traffic, allow access to these dependencies.
 
 :::note
 

package/docs/self-hosted/troubleshooting.md

@@ -202,8 +202,9 @@ to HTTPS.
 
 This redirect doesn't affect certificate issuance. cert-manager creates a
 separate challenge Ingress that continues to serve on port 80. To test the
-ingress, use a hostname with no Ingress, as described in
-[Verify your install](./verify.md).
+ingress, use a hostname with no Ingress. The
+[Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor) CLI does
+this for you in its `ingress-reachable` check.
 
 ## Failed to deploy the environment but the cluster shows the build succeeding
 

package/docs/self-hosted/upgrade.md

@@ -41,13 +41,13 @@ installed with `helm plugin install https://github.com/databus23/helm-diff`.
 
 ## Verify the upgrade
 
-Work through [Verify your install](./verify.md) again. The gateway deployments
-already in the cluster keep serving through the upgrade; they are rebuilt only
-when you deploy them.
+Run the [Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor)
+CLI again and confirm the release history records the new revision. The gateway
+deployments already in the cluster keep serving through the upgrade; they are
+rebuilt only when you deploy them.
 
 ```bash
-kubectl wait --for=condition=Available deployment --all \
-  -n zuplo-system --timeout=5m
+./zuplo-self-hosted-doctor verify
 helm history zuplo -n zuplo
 ```
 

package/package.json

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

package/docs/self-hosted/verify.md

@@ -1,279 +0,0 @@
----
-title: Verify Your Install
-sidebar_label: Verify your install
----
-
-Run the six checks in order. Each check depends on the previous one, which helps
-you identify the source of a failure. Checks one through five require only the
-installation. Check six also requires a Zuplo API key and project.
-
-## Check the deployments
-
-Gate on readiness before testing anything over the network.
-
-```bash
-kubectl wait --for=condition=Available deployment --all \
-  -n zuplo-system --timeout=5m
-kubectl wait --for=condition=Available deployment --all \
-  -n zuplo --timeout=5m
-```
-
-```
-deployment.apps/control-plane condition met
-deployment.apps/deployer condition met
-deployment.apps/gateway condition met
-deployment.apps/storage condition met
-deployment.apps/acme-forwarder condition met
-deployment.apps/custom-error-pages condition met
-deployment.apps/zuplo-cert-manager condition met
-deployment.apps/zuplo-cert-manager-cainjector condition met
-deployment.apps/zuplo-cert-manager-webhook condition met
-deployment.apps/zuplo-haproxy-ingress condition met
-deployment.apps/zuplo-kube-prometheus-stac-operator condition met
-deployment.apps/zuplo-kube-state-metrics condition met
-deployment.apps/zuplo-prometheus-adapter condition met
-```
-
-The `control-plane`, `deployer`, `gateway`, `storage`, and `acme-forwarder`
-deployments are part of the Zuplo management plane. The other deployments come
-from subcharts.
-
-## Check the ingress
-
-Send a request for a hostname that has no Ingress. This checks that the load
-balancer can reach HAProxy.
-
-```bash
-LB=$(kubectl get svc zuplo-haproxy-ingress -n zuplo \
-  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
-
-curl -i "http://$LB/" -H 'Host: no-such-deployment.example.com'
-```
-
-```
-HTTP/1.1 404 Not Found
-content-type: text/html
-
-{
-  "type": "https://httpproblems.com/http-status/404",
-  "title": "Not Found",
-  "status": 404,
-  "detail": "This Zuplo project does not exist"
-}
-```
-
-The expected result is `404 Not Found` from HAProxy's default backend. A timeout
-or refused connection means that traffic isn't reaching the ingress controller.
-
-Use a hostname without an Ingress for this check. Hosts with an Ingress redirect
-port 80 to HTTPS and return a `302` instead.
-
-:::note
-
-Requests for hosts with an Ingress are redirected from port 80 to 443. The
-separate challenge Ingress created by cert-manager continues to serve ACME
-challenge paths on port 80.
-
-:::
-
-## Check the control plane
-
-The control plane turns your values into a `Configuration` resource, then
-creates the management API's Ingress from it.
-
-```bash
-kubectl get configuration default -n zuplo-system -o yaml
-```
-
-```yaml
-spec:
-  account:
-    name: acme-corp
-  builder:
-    registry: us-docker.pkg.dev/acme-corp/zuplo-gateways
-    secretName: builder-secret
-  deployments:
-    subdomain: api.example.com
-    certificates:
-      certManager:
-        issuer: zuplo-cluster-issuer
-  managementApi:
-    hostname: zuplo-admin.example.com
-  ingressControllers:
-    - haproxy
-```
-
-Confirm every value matches what you put in `zuplo-values.yaml`. A
-single-cluster installation has no `workers` or `authorization` entry. Those
-settings are for installations that distribute deployments across clusters.
-
-Then confirm the reconciler acted on the rest:
-
-```bash
-kubectl get ingress -n zuplo-system
-kubectl get clusterissuer
-```
-
-```
-NAME              CLASS     HOSTS                       ADDRESS        PORTS     AGE
-gateway-haproxy   haproxy   zuplo-admin.example.com     203.0.113.24   80, 443   62s
-
-NAME                   READY   STATUS                                                 AGE
-zuplo-cluster-issuer   True    The ACME account was registered with the ACME server    116s
-```
-
-`READY: True` for `zuplo-cluster-issuer` means that the chart registered an
-account with the certificate authority. It doesn't indicate whether a
-certificate has been issued.
-
-:::note
-
-`Configuration` doesn't report a status. Check the Ingress and ClusterIssuer
-resources that it produces instead.
-
-:::
-
-## Check certificate issuance
-
-Check that the certificate authority issued a certificate for the management API
-hostname:
-
-```bash
-kubectl get certificate -A
-```
-
-```
-NAMESPACE      NAME                   READY   SECRET                 AGE
-zuplo-system   gateway-cert-manager   True    gateway-cert-manager   4m
-```
-
-`READY: True` means that the certificate authority validated your hostname and
-issued a certificate. If it remains `False` for more than a few minutes, see
-[Troubleshooting](./troubleshooting.md).
-
-cert-manager retries automatically after you fix DNS. You don't need to restart
-it.
-
-## Check the management API
-
-Send an unauthenticated request to check DNS, the load balancer, HAProxy, the
-certificate, and authentication:
-
-```bash
-curl -i https://zuplo-admin.example.com/v1/deployments
-```
-
-```
-HTTP/2 401
-
-{
-  "type": "https://httpproblems.com/http-status/401",
-  "title": "Unauthorized",
-  "status": 401,
-  "detail": "No Authorization Header",
-  ...
-}
-```
-
-The expected result is `401 Unauthorized`. It confirms that `curl` completed a
-TLS handshake with a trusted certificate and that the gateway requires an API
-key. A TLS error indicates a certificate problem. A timeout indicates a DNS or
-load balancer problem.
-
-Confirm the certificate is the real one rather than HAProxy's self-signed
-fallback:
-
-```bash
-echo | openssl s_client -connect zuplo-admin.example.com:443 \
-  -servername zuplo-admin.example.com 2>/dev/null |
-  openssl x509 -noout -subject -issuer
-```
-
-```
-subject=CN=zuplo-admin.example.com
-issuer=C=US, O=Let's Encrypt, CN=YR2
-```
-
-An issuer of `CN=kubernetes-ingress-ca` means HAProxy is serving its built-in
-fallback certificate because no issued certificate is available. Repeat the
-certificate issuance check.
-
-## Deploy and call a project
-
-The final check builds a gateway image in your cluster, stores it in your
-registry, and serves it from your infrastructure.
-
-Deploy your project with the Zuplo CLI. The `project` field in `zuplo.jsonc`
-selects the project, and Zuplo routes the deployment to your cluster:
-
-```bash
-export ZUPLO_API_KEY='<your Zuplo API key>'
-
-npx zuplo deploy
-```
-
-Zuplo compiles the project, then hands the compiled bundle to your cluster's
-management API, which builds the container image and rolls it out.
-
-While the command runs, watch the build Job in your cluster:
-
-```bash
-kubectl get jobs -n zuplo-system -w
-```
-
-```
-NAME                       STATUS     COMPLETIONS   DURATION   AGE
-build-basic-main-ca9748b-ztcwzdd   Running    0/1     32s   32s
-build-basic-main-ca9748b-ztcwzdd   Complete   1/1     58s   63s
-```
-
-Confirm that the deployment uses an image from your registry:
-
-```bash
-kubectl get deploy -n zuplo -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.template.spec.containers[0].image}{"\n"}{end}'
-```
-
-```
-basic-main-ca9748b	us-docker.pkg.dev/acme-corp/zuplo-gateways/basic-main-ca9748b:20260806-172436
-```
-
-Ask the management API what it is serving:
-
-```bash
-curl -H "Authorization: Bearer $ZUPLO_API_KEY" \
-  https://zuplo-admin.example.com/v1/deployments
-```
-
-```json
-{
-  "data": [
-    {
-      "projectName": "basic",
-      "deploymentName": "basic-main-ca9748b-haproxy",
-      "deploymentUrl": "https://basic-main-ca9748b.api.example.com"
-    }
-  ]
-}
-```
-
-Call the deployed API:
-
-```bash
-curl https://basic-main-ca9748b.api.example.com/hello
-```
-
-The first request to a deployment can fail while cert-manager issues its
-certificate. Retry the request for up to a minute.
-
-:::note
-
-The CLI can misreport the status of deployments to self-hosted clusters. See
-[Troubleshooting](./troubleshooting.md#failed-to-deploy-the-environment-but-the-cluster-shows-the-build-succeeding).
-Use the in-cluster checks to confirm the result.
-
-:::
-
-## Resolve a failed check
-
-[Troubleshooting](./troubleshooting.md) lists errors from these checks and their
-causes.