zuplo 7.1.0 → 7.1.2

package/docs/ai-gateway/apps.mdx

@@ -1,22 +1,40 @@
 ---
 title: AI Gateway Apps
 sidebar_label: Overview
+description:
+  Apps represent the services and integrations that call your AI Gateway. Each
+  app has its own URL, API key, and policy chain.
 ---
 
-Apps in the Zuplo AI Gateway represent any app or integration that will call the
-AI Gateway. For example, you might have a custom support chatbot on your
-website - that chatbot would be an App in the AI Gateway. Each App has its own
-API Key so that usage is tracked independently. Apps are owned by a specific
-[team](./teams.mdx) and can access the AI Providers assigned to that team.
+An app represents one caller of your AI Gateway—a service, an agent, or a
+feature in a larger codebase. A support chatbot on your website is one app; the
+batch job that summarizes tickets overnight is another. Each app belongs to a
+[team](./teams.mdx) and can reach the AI providers assigned to that team.
+
+Each app has three things of its own:
+
+- **An API URL**—the endpoint the app's code calls, shown at the top of the app
+  page. The gateway attributes requests made to this URL to the app, tracking
+  usage independently per app. See the [Universal API](./universal-api.mdx).
+- **An API key**—authenticates the app's requests when the gateway runs the
+  [authentication policy](./policy-chains.mdx#authentication).
+- **A [policy chain](./policy-chains.mdx)**—the ordered policies that run on the
+  app's requests: model access, budgets, caching, guardrails, and custom
+  policies. The chain starts out empty unless the app's team has a
+  [policy template](./policy-templates.mdx).
 
 ## API Keys
 
-Each App in the AI Gateway has its own API Key. This allows you to track usage
-independently for each App. You can find the API Key for an App by opening the
+Each app has its own API key, which the gateway validates when the
+[authentication policy](./policy-chains.mdx#authentication) applies. The key is
+optional: the gateway attributes usage by app ID, resolving it either from a
+validated key or from the `{app_id}` segment of the request URL, so an app
+without authentication still tracks usage independently.
+
+To find an app's API key, open the
 [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of your AI
-Gateway project in the Zuplo Portal. Select the App you want to view the API Key
-for. With the App open you will see the API Key section at the top of the app
-page.
+Gateway project in the Zuplo Portal and select the app. The API key appears in
+the API Key section at the top of the app page.
 
 **Additional Resources**
 

package/docs/ai-gateway/cookbooks/custom-fallback.mdx

@@ -0,0 +1,96 @@
+---
+title: "Cookbook: Custom fallback logic"
+sidebar_label: Custom fallback logic
+description:
+  Write a custom policy that chooses a backup model dynamically—for example,
+  picking any active Anthropic model as the fallback—instead of a fixed entry in
+  the Fallback Model policy.
+---
+
+The [Fallback Model policy](../fallback.mdx) covers a fixed backup and quota
+fallback. When the backup should be chosen dynamically—the cheapest available
+model, a provider-specific preference, whatever is currently active—a custom
+[chain policy](../custom-policies.mdx) can replace it using the same public
+primitives.
+
+A fallback policy enriches the selection an earlier policy created. Because
+`AIGatewayModelRouting.set()` replaces the complete stored selection rather than
+partially updating it, the policy must read, merge, and set. It should also
+leave the request unchanged when no earlier policy created a selection—so a
+misplaced chain entry doesn't bypass model filtering—and when the chosen backup
+equals the current main model, which `set()` rejects.
+
+## The policy
+
+This example adds the first active Anthropic completions model as the backup,
+with a 30-second timeout:
+
+```ts title="modules/add-fallback.ts"
+import {
+  AIGatewayModelRouting,
+  AIGatewayModels,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function addFallback(
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<ZuploRequest> {
+  const routing = AIGatewayModelRouting.get(context);
+  const current = routing?.completions;
+  if (!routing || !current) {
+    return request;
+  }
+  const target = typeof current === "string" ? { main: current } : current;
+
+  const providers = await AIGatewayModels.load(context);
+  const anthropic = providers.find(
+    (provider) => provider.providerName === "anthropic",
+  );
+  const fallback = anthropic?.models.find(
+    (candidate) =>
+      candidate.capability === "completions" && candidate.status === "active",
+  );
+  const backup = fallback ? `anthropic/${fallback.model}` : undefined;
+  if (!backup || backup.toLowerCase() === target.main.toLowerCase()) {
+    return request;
+  }
+
+  await AIGatewayModelRouting.set(context, {
+    ...routing,
+    completions: {
+      ...target,
+      backup,
+      fallbackTimeoutSeconds: 30,
+    },
+  });
+  return request;
+}
+```
+
+## Declare and use it
+
+```json title="config/policies.json (one entry in the policies array)"
+{
+  "name": "add-fallback",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/add-fallback)"
+  }
+}
+```
+
+Add `add-fallback` to an app's chain directly after Model Filtering, replacing
+the Fallback Model policy. Keep the no-selection guard at the top of the
+policy—it prevents a misplaced entry from creating a primary selection and
+bypassing filtering.
+
+## Next steps
+
+- [Fallback Models](../fallback.mdx): the built-in fallback and quota-fallback
+  behavior
+- [Cookbook: Dynamic model routing](./dynamic-model-routing.mdx): create the
+  primary selection from code
+- [Custom Policies](../custom-policies.mdx): the full custom-policy quickstart

package/docs/ai-gateway/cookbooks/dynamic-model-routing.mdx

@@ -0,0 +1,119 @@
+---
+title: "Cookbook: Dynamic model routing"
+sidebar_label: Dynamic model routing
+description:
+  Write a custom policy that picks the model per request—for example, always
+  routing to the cheapest active model—using the AI Gateway's public routing
+  primitives.
+---
+
+The Model Filtering policy covers static allow and block lists, but model
+selection can also be code. A custom [chain policy](../custom-policies.mdx) can
+pick the model per request based on price, capability, the calling app, or
+anything else in the request. This recipe routes every request to the cheapest
+active completions model.
+
+Two public primitives from `@zuplo/runtime` do the work:
+
+- `AIGatewayModels.load(context)` returns the cached provider catalog, including
+  each model's capability, status, and per-token pricing. Credentials are never
+  returned.
+- `AIGatewayModelRouting.set(context, routing)` validates the routing, resolves
+  provider credentials internally, and stores the selection the AI Gateway
+  handler uses. `AIGatewayModelRouting.get(context)` reads the current
+  selection.
+
+## The policy
+
+```ts title="modules/cheapest-model.ts"
+import {
+  AIGatewayModelRouting,
+  AIGatewayModels,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+interface CheapestModelOptions {
+  providers?: string[];
+}
+
+export default async function cheapestModel(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: CheapestModelOptions,
+): Promise<ZuploRequest | Response> {
+  const allowed = options.providers ?? ["openai", "anthropic"];
+  const candidates = (await AIGatewayModels.load(context))
+    .filter(({ providerName }) => allowed.includes(providerName.toLowerCase()))
+    .flatMap((provider) =>
+      provider.models.map((model) => ({
+        providerName: provider.providerName,
+        model,
+      })),
+    )
+    .filter(
+      ({ model }) =>
+        model.capability === "completions" && model.status === "active",
+    )
+    .sort(
+      (left, right) =>
+        left.model.inputCostPerToken +
+        left.model.outputCostPerToken -
+        (right.model.inputCostPerToken + right.model.outputCostPerToken),
+    );
+
+  const cheapest = candidates[0];
+  if (!cheapest) {
+    // Returning a Response short-circuits the chain and answers the request.
+    return new Response("No eligible model", { status: 503 });
+  }
+
+  await AIGatewayModelRouting.set(context, {
+    completions: `${cheapest.providerName}/${cheapest.model.model}`,
+  });
+  return request;
+}
+```
+
+## Declare and use it
+
+Declare the module in `config/policies.json` and push:
+
+```json title="config/policies.json (one entry in the policies array)"
+{
+  "name": "cheapest-model",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/cheapest-model)",
+    "options": {
+      "providers": ["openai", "anthropic"]
+    }
+  }
+}
+```
+
+Then add `cheapest-model` to an app's chain on its Policies tab, in place of
+Model Filtering.
+
+## Routing precedence
+
+Policy order determines which selection wins:
+
+1. Routing selected before Model Filtering stays authoritative—Model Filtering
+   leaves an existing selection unchanged.
+2. Model Filtering creates routing when no earlier policy selected it.
+3. A custom policy placed after Model Filtering may deliberately replace that
+   selection.
+4. If no policy selects routing, the handler derives it from the request's
+   `providerName/model`.
+
+Prefer one policy as the primary selector so the route's intent is easy to
+understand.
+
+## Next steps
+
+- [Custom Policies](../custom-policies.mdx): the full custom-policy quickstart
+- [Cookbook: Custom fallback logic](./custom-fallback.mdx): enrich a selection
+  instead of creating one
+- [Policy Chains](../policy-chains.mdx): how chain order works

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

@@ -0,0 +1,213 @@
+---
+title: "Quickstart: Write a Custom Policy"
+sidebar_label: Custom Policies
+description:
+  Write a custom AI Gateway policy in TypeScript—a content filter that blocks
+  prompts containing banned terms—declare it in policies.json, deploy it with a
+  push, and add it to an app's policy chain in the portal.
+---
+
+The AI Gateway's built-in policies cover model access, budgets, caching,
+guardrails, and tracing—but your gateway can run any policy you can write in
+TypeScript. A custom policy lives in your gateway's
+[repository](./source-control.mdx), is declared in `config/policies.json`, and
+from then on appears in the portal's **Add Policy** dialog like any built-in
+policy. Apps add it to their [policy chains](./policy-chains.mdx), and it runs
+on every request for those apps.
+
+This quickstart builds a content filter that blocks prompts containing banned
+terms. By the end, one app on your gateway rejects a prompt containing
+"acme-secret-project" with a `400` response, while other apps are unaffected.
+
+## Prerequisites
+
+- An AI Gateway project connected to a Git repository, with a provider, a team,
+  and an app—the [Getting Started](./getting-started.mdx) guide covers this
+- A local clone of the gateway's repository
+
+<Stepper>
+
+1. **Write the policy module**
+
+   In your clone of the gateway repository, create a `modules/` directory next
+   to `config/` if it doesn't exist yet, and add `modules/content-filter.ts`. A
+   policy is a function that receives the request, a context, and the options
+   configured for it—and returns the request to continue the chain, or a
+   `Response` to answer immediately:
+
+   ```ts title="modules/content-filter.ts"
+   import type { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+   interface ContentFilterOptions {
+     blockedTerms: string[];
+   }
+
+   export default async function contentFilter(
+     request: ZuploRequest,
+     context: ZuploContext,
+     options: ContentFilterOptions,
+   ): Promise<ZuploRequest | Response> {
+     const body = await request.clone().json();
+     const text = JSON.stringify(body.messages ?? body.input ?? "");
+
+     const match = options.blockedTerms.find((term) =>
+       text.toLowerCase().includes(term.toLowerCase()),
+     );
+
+     if (match) {
+       context.log.warn(
+         `Blocked request from app ${request.user?.sub}: matched "${match}"`,
+       );
+       return new Response(
+         JSON.stringify({
+           error: {
+             message: "This request was blocked by your content policy.",
+             type: "invalid_request_error",
+           },
+         }),
+         { status: 400, headers: { "content-type": "application/json" } },
+       );
+     }
+
+     return request;
+   }
+   ```
+
+   The calling app is available on `request.user` when the request's API key
+   resolves to one—`sub` is the app's name—so a policy can log, branch, or
+   report per app. It can be `undefined`, so use optional chaining. The example
+   inspects chat and response payloads; embeddings requests pass through
+   unfiltered.
+
+2. **Declare the policy in `config/policies.json`**
+
+   The repository already contains `config/policies.json` with the built-in
+   policy declarations. Add one more entry to its `policies` array—the entry's
+   `name` is how the policy appears in the portal. The declaration makes the
+   policy available for apps to select; it doesn't run for any app yet:
+
+   ```json title="config/policies.json (one entry in the policies array)"
+   {
+     "name": "content-filter",
+     "policyType": "custom-code-inbound",
+     "handler": {
+       "export": "default",
+       "module": "$import(./modules/content-filter)",
+       "options": {
+         "blockedTerms": ["acme-secret-project"]
+       }
+     }
+   }
+   ```
+
+3. **Deploy**
+
+   Commit both files and push to your default branch:
+
+   ```bash
+   git add modules/content-filter.ts config/policies.json
+   git commit -m "Add content-filter policy"
+   git push
+   ```
+
+   The next production deploy puts the new policy on the menu—with GitHub, the
+   push itself deploys; see [Source Control](./source-control.mdx) for the other
+   Git providers.
+
+4. **Add the policy to an app's chain**
+
+   In the Zuplo Portal, open
+   [**Apps**](https://portal.zuplo.com/+/account/project/ai/apps), select your
+   app, and open its **Policies** tab. Click **Add Policy**—`content-filter` now
+   appears alongside the built-in policies. Add it, drag it to where in the
+   chain it should run, and save.
+
+   :::tip{title="Where in the chain?"}
+
+   If the chain has the Budgets and Costs policy, placing the filter before it
+   means blocked requests aren't counted against the app's budget; placing it
+   after means they are. The same reasoning applies to any policy that can
+   answer a request itself.
+
+   :::
+
+   The change applies within about a minute—no deploy.
+
+5. **Test it**
+
+   Send a prompt containing a blocked term through the app, using the URL and
+   API key from the app page (the URL below is a stand-in for it):
+
+   ```bash
+   curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
+     -H "Authorization: Bearer YOUR_APP_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "model": "openai/gpt-5-mini",
+       "messages": [{"role": "user", "content": "Tell me about acme-secret-project"}]
+     }'
+   ```
+
+   The gateway answers with the policy's `400` response. Send a harmless prompt
+   and the request flows through to the provider as usual. Apps that don't
+   include `content-filter` in their chains are unaffected.
+
+</Stepper>
+
+## Per-app settings
+
+An app's chain entry can override the declared options completely. In the
+portal, edit the entry's options to give one app its own list:
+
+```json
+{
+  "blockedTerms": ["acme-secret-project", "codename-falcon"]
+}
+```
+
+An entry that overrides options replaces the declaration's entire options object
+—fields aren't merged. An entry without options inherits the declaration's
+options exactly.
+
+## Configure credentials
+
+If a policy needs a credential—say it calls an external moderation API—set it in
+the declaration's options, and let chain entries inherit it:
+
+```json title="config/policies.json"
+{
+  "name": "my-moderation-policy",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/my-moderation-policy)",
+    "options": {
+      "apiKey": "your-moderation-api-key"
+    }
+  }
+}
+```
+
+Leave the chain entry's options out so it inherits the declaration's values—an
+entry that sets its own options replaces them completely.
+
+## Beyond filtering
+
+A custom policy can do more than block requests—the cookbooks walk through
+complete recipes:
+
+- **Route models dynamically.** Read the live model catalog and select the model
+  per request—for example, always the cheapest active model. See
+  [Dynamic model routing](./cookbooks/dynamic-model-routing.mdx).
+- **Choose fallbacks from code.** Enrich the model selection with a dynamically
+  chosen backup. See [Custom fallback logic](./cookbooks/custom-fallback.mdx).
+- **Enrich or annotate.** Add headers, log structured events, or call out to
+  other services.
+
+## Next steps
+
+- [Policy Chains](./policy-chains.mdx): execution order, options inheritance,
+  and the built-in policies
+- [Policy Templates](./policy-templates.mdx): roll a custom policy out to every
+  new app in a team
+- [Source Control](./source-control.mdx): how repository changes deploy

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

@@ -1,6 +1,10 @@
 ---
 title: Using Custom AI Providers
 sidebar_label: Custom Providers
+description:
+  Route AI Gateway apps to self-hosted or third-party OpenAI-compatible services
+  by adding a custom provider with its own name, URL, models, and optional
+  per-token costs.
 ---
 
 Zuplo's AI Gateway supports the addition of custom AI providers. This allows
@@ -29,8 +33,12 @@ To add a custom AI provider to your Zuplo AI Gateway, follow these steps:
 
 1. Select the **Custom** option from the Custom Providers section of the list
 
-1. Specify a label for the custom provider instance. You can change the label
-   later if required.
+1. Replace the pre-filled **Provider Name** (`custom`) with a name for your
+   provider. The name is how apps reference the provider's models: a custom
+   provider named `acme-llm` serves models as `acme-llm/<model>`. Names are
+   lowercase (letters, numbers, dots, dashes, and underscores), and the built-in
+   provider names (`openai`, `anthropic`, `google`, `mistral`, `xai`,
+   `moonshot`) are reserved. The name is permanent after creation.
 
 1. Specify the API URL of the custom provider you are using.
 

package/docs/ai-gateway/fallback.mdx

@@ -2,64 +2,51 @@
 title: Fallback Models
 sidebar_label: Fallbacks
 description:
-  Configure error, timeout, and quota fallback models for an AI Gateway app in
-  the Zuplo Portal so it keeps serving requests when the primary model fails or
-  goes over quota.
+  Configure error, timeout, and quota fallback models for an AI Gateway app so
+  it keeps serving requests when the primary model fails or goes over quota.
 ---
 
-Each AI Gateway app calls a primary model: the provider, completions model, and
-optional embeddings model you select under **AI Models** on the app's
-**Settings** tab. Fallbacks let an app keep serving requests when that primary
-model fails, times out, or runs over its usage limits, instead of returning an
-error to the caller.
+Fallbacks let an app keep serving requests when its primary model fails, times
+out, or runs over its usage limits, instead of returning an error to the caller.
+They're configured with the **Fallback Model** policy in the app's
+[policy chain](./policy-chains.mdx).
 
 The AI Gateway offers two independent fallback mechanisms, each triggered by a
 different condition:
 
-| Mechanism              | Triggers when…                                           | Without a fallback set…             |
-| ---------------------- | -------------------------------------------------------- | ----------------------------------- |
-| **Fallback & Timeout** | The primary returns a `4xx`/`5xx` or exceeds the timeout | The error is returned to the caller |
-| **Quota Fallback**     | One of the app's usage limits is exceeded                | The request is blocked with a `429` |
+| Mechanism              | Triggers when…                                                                                         | Without a fallback set…                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| **Fallback & Timeout** | The primary fails with a retryable error (`5xx`, `408`, `425`, `429`), a network failure, or a timeout | The gateway returns the error to the caller |
+| **Quota Fallback**     | One of the app's usage limits is exceeded                                                              | The request is blocked with a `429`         |
 
 Both are configured entirely in the Zuplo Portal, and either can route to _any_
-provider. The fallback doesn't have to share the primary's provider.
+provider—the fallback doesn't have to share the primary's provider. Fallback
+models are referenced like any model, as `providerName/model`.
 
-## Error and timeout fallback
-
-The **Fallback & Timeout** section fails an app over to a second model when the
-primary model returns a `4xx` or `5xx` response, or when the request takes
-longer than the configured timeout. This protects against provider outages, rate
-limiting on the primary provider, and slow responses.
-
-### Configure an error and timeout fallback
+## Configure fallbacks
 
 <Stepper>
 
 1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of
    your AI Gateway project and select the app to edit.
 
-1. Select the **Settings** tab and find the **Fallback & Timeout** section.
-
-1. Choose a **Fallback Provider**. This can be the same provider as the primary
-   or a different one, including a [custom provider](./custom-providers.mdx).
+1. Select the **Policies** tab. If the chain doesn't have a **Fallback Model**
+   policy yet, click **Add Policy** and add it—placed directly after Model
+   Filtering.
 
-1. Select the **Fallback Completions** model. If the app uses embeddings, also
-   select a **Fallback Embeddings** model.
+1. Configure the policy:
+   - **Fallback**: the model attempted after a retryable error or timeout, for
+     example `anthropic/claude-haiku-4-5`.
+   - **Quota fallback**: the model used once a usage limit is exceeded, for
+     example `openai/gpt-4o-mini`.
+   - **Fallback timeout (seconds)**: how long the primary call can run before
+     the gateway fails over. The default is `60`; values from `1` to `300` are
+     accepted.
 
-1. Set the **Request timeout (seconds)** value to bound how long the primary
-   model call can run before the gateway fails over. The default is `60`, but
-   you can set any value that suits your app.
-
-1. Click **Save Changes**.
+1. Save. The change applies within about a minute.
 
 </Stepper>
 
-<Framed>
-
-![The Fallback & Timeout section of the app Settings tab, showing the Fallback Provider, Fallback Completions, Fallback Embeddings, and Request timeout fields](./fallback-and-timeout.png)
-
-</Framed>
-
 :::note
 
 The request timeout applies _only_ when a fallback model is set. If no fallback
@@ -69,38 +56,16 @@ is configured, the primary model call runs unbounded.
 
 ## Quota fallback
 
-The **Quota Fallback** section routes requests to an alternate, usually cheaper,
-model when one of the app's [usage limits](./usage-limits.mdx) is exceeded,
-rather than blocking the request with a `429`. This keeps an app available after
-it crosses a budget, token, or request threshold, while shifting the overflow
-traffic to a lower-cost model.
-
-If you leave the quota fallback empty, the app blocks requests with a `429` once
-it goes over quota.
-
-### Configure a quota fallback
-
-<Stepper>
-
-1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab and
-   select the app to edit.
+The quota fallback routes requests to an alternate, usually cheaper, model when
+one of the app's [usage limits](./usage-limits.mdx) is exceeded, rather than
+blocking the request with a `429`. This keeps an app available after it crosses
+a budget, token, or request threshold, while shifting the overflow traffic to a
+lower-cost model.
 
-1. Select the **Settings** tab. Set the limits you want to enforce under **Usage
-   Limits & Thresholds**, then find the **Quota Fallback** section below them.
-
-1. Choose a **Quota Fallback Provider**, then select the **Quota Fallback
-   Completions** model. If the app uses embeddings, also select a **Quota
-   Fallback Embeddings** model.
-
-1. Click **Save Changes**.
-
-</Stepper>
-
-<Framed>
-
-![The Quota Fallback section of the app Settings tab, below Usage Limits & Thresholds, showing the Quota Fallback Provider, Quota Fallback Completions, and Quota Fallback Embeddings fields](./quota-fallback.png)
-
-</Framed>
+For the quota fallback to activate, the chain needs the **Budgets and Costs**
+policy after Fallback Model—it detects the exceeded limit and switches to the
+fallback selection. If you leave the quota fallback empty, the app blocks
+requests with a `429` once it goes over quota.
 
 :::tip
 
@@ -115,18 +80,26 @@ toward the app's limits.
 The mechanisms are evaluated independently and can both be active on the same
 app:
 
-- A request that is **over quota** routes to the quota fallback model.
-- A request that is **within quota** but hits an **error or timeout** on the
+- A request that's **over quota** routes to the quota fallback model.
+- A request that's **within quota** but hits an **error or timeout** on the
   primary routes to the error and timeout fallback model.
 
 Set whichever fallbacks match the failure modes you want to protect against.
 Neither is required.
 
+:::note
+
+Error and timeout fallback applies to Chat Completions and Embeddings requests.
+Requests to the native `/v1/messages` and `/v1/responses` endpoints pass through
+without retrying a backup model; the quota fallback still applies to them.
+
+:::
+
 ## Related resources
 
-- [Managing Apps](./managing-apps.mdx) - Create, edit, and delete AI Gateway
-  apps.
-- [Usage Limits & Thresholds](./usage-limits.mdx) - Configure the budget, token,
-  and request limits that trigger a quota fallback.
+- [Policy Chains](./policy-chains.mdx) - How the app's policy chain executes and
+  the recommended policy order.
+- [Usage Limits](./usage-limits.mdx) - Configure the budget, token, and request
+  limits that trigger a quota fallback.
 - [Custom Providers](./custom-providers.mdx) - Add your own provider to use as a
   primary or fallback model.