zuplo 7.7.10 → 7.7.11

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/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/self-hosted/install.md

@@ -168,4 +168,38 @@ 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.
 
-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/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.11",
   "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.11",
+    "@zuplo/core": "7.7.11",
+    "@zuplo/runtime": "7.7.11",
+    "@zuplo/test": "7.7.11"
   }
 }

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.