zuplo 7.1.1 → 7.1.2

package/docs/ai-gateway/policies/galileo-tracing.mdx

@@ -1,6 +1,9 @@
 ---
-title: Galileo Tracing
-sidebar_label: Galileo Tracing
+title: Galileo tracing
+sidebar_label: Galileo tracing
+description:
+  Send LLM traces from the Zuplo AI Gateway to Galileo for monitoring,
+  debugging, and quality evaluation of your AI applications.
 ---
 
 The Galileo Tracing policy integrates [Galileo AI](https://www.galileo.ai/) with
@@ -36,7 +39,7 @@ For each request, the policy automatically captures:
 **Request Information**
 
 - User prompts and messages
-- Model parameters (temperature, max_tokens, etc.)
+- Model parameters (temperature, `max_tokens`, etc.)
 - Request metadata (route, request ID)
 - Timestamp and duration
 
@@ -64,23 +67,6 @@ For each request, the policy automatically captures:
     2. Create a new project in your Galileo dashboard
     3. Generate an API key specifically for use with Zuplo
 
-2.  ### Add the policy to your app
-
-    You can add the policy to any AI Gateway app by clicking on **Policies**,
-    then on **Add Policy** and select **Galileo Tracing**.
-
-    ![The AI Gateway policy picker](../../../public/media/galileo-tracing/galileo-tracing-1.png)
-
-3.  ### Configure the policy
-
-    You will need to enter the following information from your Galileo account
-    to configure the policy:
-    - **`apiKey`**: Your Galileo API key for authentication
-    - **`projectId`**: The Galileo project ID to send traces to
-    - **`logStreamId`**: The specific log stream within your project
-    - **`baseUrl`** (optional): Custom Galileo API endpoint (defaults to
-      `https://api.galileo.ai`)
-
     :::note
 
     The `projectId` and `logStreamId` are both found in the URL of the Galileo
@@ -92,6 +78,34 @@ For each request, the policy automatically captures:
 
     :::
 
+2.  ### Configure the declaration in your gateway's repository
+
+    The scaffolded gateway declares the Galileo Tracing policy in
+    `config/policies.json`. Set its settings and push:
+
+    ```json title="config/policies.json"
+    {
+      "name": "galileo-tracing-v2-inbound",
+      "policyType": "galileo-tracing-v2-inbound",
+      "handler": {
+        "export": "GalileoTracingV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "apiKey": "your-galileo-api-key",
+          "projectId": "3e71c65e-48b6-4f5d-842d-0851c4704f95",
+          "logStreamId": "f8c71402-1f6b-4f5b-b073-1de999e6a8ea"
+        }
+      }
+    }
+    ```
+
+3.  ### Add the policy to your app
+
+    Open the app's **Policies** tab, click **Add Policy**, and select **Galileo
+    Tracing**. Place it at the end of the chain so traces reflect the request
+    the provider actually receives. The app inherits the configuration from the
+    declaration.
+
 </Stepper>
 
 ### Key Metrics
@@ -139,8 +153,8 @@ Common issues and solutions:
 
 - **Authentication Errors**: Check that your Galileo API key is valid and has
   proper permissions
-- **Configuration Issues**: Ensure the user context includes all required
-  Galileo settings
+- **Configuration Issues**: Ensure the policy declaration's environment
+  variables are set in your project settings
 
 ## Additional Resources
 

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

@@ -0,0 +1,47 @@
+---
+title: Budgets and Costs
+sidebar_label: Budgets and Costs
+description:
+  Record an app's usage and enforce its budgets for spend, tokens, and requests.
+---
+
+`ai-gateway-metering-v2`
+
+The **Budgets and Costs** policy records what an app uses and enforces its
+budgets. It meters three things—spend, tokens, and requests—each with
+independent daily and monthly periods, and each with an optional warning
+threshold that notifies without blocking.
+
+When a limit is exceeded, the policy either routes the request to the model
+selection's `quotaFallback` if [Fallback Model](./fallback-model.mdx) supplied
+one, or rejects it with `429`.
+
+An app's own limits aren't the only ones that apply. The policy also checks the
+parent team's and the gateway's limits, which are enforced centrally rather than
+from this policy's options—so a request can be blocked by a limit that isn't
+visible in the app's chain.
+
+Place Budgets and Costs after [Model Filtering](./model-filtering.mdx) and
+[Fallback Model](./fallback-model.mdx), so an exceeded budget can activate the
+quota fallback.
+
+:::caution{title="Budgets fail open by default"}
+
+`throwOnFailure` defaults to `false`, so if the metering service is unavailable
+the request proceeds unmetered—no limit is checked, even for an app that's
+already over budget. Set it to `true` to reject the request instead.
+
+:::
+
+:::note
+
+Each limit period carries an `enabled` flag next to its number, and so does each
+warning threshold. A period enforces nothing until `enabled` is `true` _and_
+`limit` is set. Watch for this when editing options directly, such as in
+`config/policies.json` or a [policy template](../policy-templates.mdx).
+
+:::
+
+For the portal workflow and the gateway and team levels see
+[Usage Limits](../usage-limits.mdx); for every option see the
+[generated reference](/policies/ai-gateway-metering-v2-inbound).

package/docs/ai-gateway/policies/model-filtering.mdx

@@ -0,0 +1,49 @@
+---
+title: Model Filtering
+sidebar_label: Model Filtering
+description:
+  Restrict an app to specific models with an allow list or block list, and set
+  the default model.
+---
+
+`ai-gateway-model-filtering-v2`
+
+Model Filtering decides which models an app may use and creates the model
+selection the rest of the chain works from. Without it, an app can reach any
+model offered by the providers assigned to its [team](../teams.mdx).
+
+Configure each capability—completions, embeddings—in one of two modes. The modes
+are mutually exclusive per capability.
+
+- An **allow list** exposes a curated set of models. The first entry is the
+  default when a request names no model.
+- A **block list** permits every available model except the ones named. Each
+  request must name its model, because a block list supplies no default.
+
+Models are written as `providerName/model`, where `providerName` is the provider
+name configured in your gateway—for example `openai/gpt-5`.
+
+## What a rejected request gets
+
+| Request                                          | Response                      |
+| ------------------------------------------------ | ----------------------------- |
+| A model the rules don't allow                    | `403`, listing what's allowed |
+| No `model` named, in block list mode             | `400`                         |
+| A capability the policy doesn't configure at all | `403`                         |
+| A provider name that isn't in the catalog        | `400`                         |
+
+Rejections are returned as problem details, and the `detail` names what the
+caller should have sent—the allowed models for a blocked model, or the gateway's
+configured provider names for an unrecognized one. The
+[Akamai AI Firewall](./akamai-ai-firewall.mdx) is the exception among the
+policies here: it answers in the provider's own error format instead.
+
+Place Model Filtering first in the chain—it creates the model selection that
+[Fallback Model](./fallback-model.mdx) and [Budgets and Costs](./metering.mdx)
+build on.
+
+For the portal workflow see
+[Restricting models](../managing-apps.mdx#restricting-models); for every option
+see the [generated reference](/policies/ai-gateway-model-filtering-v2-inbound).
+When model selection needs logic instead of a list, see
+[Dynamic model routing](../cookbooks/dynamic-model-routing.mdx).

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

@@ -0,0 +1,28 @@
+---
+title: AI Gateway policies
+sidebar_label: Overview
+description: Every policy an AI Gateway app can run, and what each one does.
+---
+
+The gateway's `config/policies.json` declares which policies apps may use, and
+each app picks from that menu in the order it wants. See
+[Policy Chains](../policy-chains.mdx) for how a chain executes and how options
+and secrets are inherited.
+
+| Policy                                                                | What it does                                                                                         |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| [API key authentication](./authentication.mdx)                        | Requires an app API key and resolves the calling app from it                                         |
+| [Model Filtering](./model-filtering.mdx)                              | Restricts the app to an allow list or block list of models, and supplies the default model           |
+| [Fallback Model](./fallback-model.mdx)                                | Adds a backup model for provider errors and timeouts, and a cheaper model for when a budget runs out |
+| [Budgets and Costs](./metering.mdx)                                   | Records usage and enforces the app's budgets for spend, tokens, and requests                         |
+| [Semantic cache](./semantic-cache.mdx)                                | Returns a cached response when a new prompt is close enough to one already seen                      |
+| [Akamai AI Firewall](./akamai-ai-firewall.mdx)                        | Scans prompts and completions with your Akamai configuration and blocks what it denies               |
+| [Comet Opik tracing](./comet-opik-tracing.mdx)                        | Sends a trace of each request and response to Comet Opik                                             |
+| [Galileo tracing](./galileo-tracing.mdx)                              | Sends a trace of each request and response to Galileo                                                |
+| [Configuration Executor](../policy-chains.mdx#configuration-executor) | Loads the app's configuration and runs its chain—this is what makes app chains work                  |
+
+The Configuration Executor sits on the gateway's route rather than in an app's
+chain. API key authentication works in either spot: in an app's chain it
+protects that app alone, and on the route it covers every app. Any
+[custom policy](../custom-policies.mdx) you declare joins the menu alongside
+these.

package/docs/ai-gateway/policies/semantic-cache.mdx

@@ -0,0 +1,48 @@
+---
+title: Semantic cache
+sidebar_label: Semantic cache
+description:
+  Return a cached response when a new prompt is close enough to one the app has
+  already answered.
+---
+
+`ai-gateway-semantic-cache-v2-inbound`
+
+The semantic cache answers a request from a previous response when the new
+prompt is semantically similar to one already seen, skipping the provider
+entirely. One policy handles both halves: it checks the cache on the way in and,
+on a miss, stores the provider's response on the way out. There's no separate
+outbound policy to add.
+
+A cache hit answers the request, so entries after it in the chain don't run.
+Place it after [Budgets and Costs](./metering.mdx) so hits still count toward
+the app's request limits.
+
+## Options
+
+| Option                  | Default                              | What it does                                                                                        |
+| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `semanticTolerance`     | `0.2`                                | How loose a match to accept. A response is reused at similarity ≥ 1 − tolerance, so `0.2` needs 0.8 |
+| `expirationSecondsTtl`  | `3600`                               | How long a cached response stays valid, up to 30 days                                               |
+| `maxConversationLength` | `3`                                  | Longest conversation to cache, in messages                                                          |
+| `endpoints`             | Chat Completions, Anthropic Messages | Which API shapes to cache                                                                           |
+| `namespace`             | The app's ID                         | Cache partition. Only applies when the request has no app configuration                             |
+
+## What isn't cached
+
+- Conversations longer than `maxConversationLength`—three messages by
+  default—aren't cached at all.
+- The Responses API isn't supported. The cache covers Chat Completions and
+  Anthropic Messages.
+- The cache always fails open: if the cache is unavailable, the request goes to
+  the provider as normal.
+
+One app can never read another's cached responses. The namespace is fixed to the
+app's ID whenever the request resolves to an app, so the `namespace` option only
+matters on a gateway that doesn't identify apps.
+
+## Reading cache outcomes
+
+Each response carries the outcome as a `Cache-Status` header under the cache
+name `zp-aigw-sem-cache`, alongside `x-ai-gateway-cache` (`HIT` or `MISS`) and
+`x-ai-gateway-cache-similarity`.

package/docs/ai-gateway/policy-chains.mdx

@@ -0,0 +1,178 @@
+---
+title: AI Gateway Policy Chains
+sidebar_label: Policy Chains
+description:
+  Each AI Gateway app runs an ordered chain of policies selected from the
+  gateway's policies.json. Learn how the chain executes, how options and secrets
+  are inherited, and the recommended policy order.
+---
+
+Every request to an AI Gateway app runs down through the app's **policy chain**:
+an ordered list of policies that control model access, budgets, caching,
+guardrails, and tracing for that app. Different apps on the same gateway can run
+completely different chains.
+
+The chain works in two layers:
+
+- **The gateway declares the menu.** `config/policies.json` in the gateway's
+  [repository](./source-control.mdx) declares every policy that apps may use
+  —built-in AI Gateway policies and any [custom policies](./custom-policies.mdx)
+  you write. Changing the menu is a repository change that takes effect on the
+  next production deploy.
+- **Each app selects from the menu.** An app's chain—which policies run, in what
+  order, with what settings—is edited on the app's **Policies** tab in the
+  portal. Chain changes apply within about a minute, with no deploy.
+
+No policy is required. An app whose chain is empty still serves requests: each
+request names its own model, and no model restrictions, budgets, guardrails, or
+caching apply. Every control is something you add.
+
+A request passes through whatever the app selected before the AI Gateway handler
+calls the provider:
+
+```text
+Request
+  → Model Filtering   ─┐
+  → Budgets and Costs  ├─ the app's policy chain
+  → Custom policy     ─┘
+  → AI Gateway handler
+  → LLM provider
+```
+
+## Editing a chain
+
+The app's **Policies** tab shows the chain in execution order. Drag entries to
+reorder them, and click **Add Policy** to add one from the gateway's menu.
+
+Each declared policy has a single **Add** button. For a policy with settings,
+Add opens its settings screen, where you confirm or change the values before the
+policy joins the chain. For a policy with no settings screen, Add puts it
+straight into the chain with the options declared in `policies.json`.
+
+A policy that's already in the chain shows **Already added** instead of a
+button—edit it in the chain instead.
+
+Entries seeded by a [team policy template](./policy-templates.mdx) may be
+locked: a lock icon means the template controls whether this app may edit or
+remove that entry.
+
+## How the chain executes
+
+- Entries run in the listed order, after the gateway's route-level policies and
+  before the AI Gateway handler calls the provider.
+- A policy can answer the request itself—for example, a semantic cache hit or a
+  guardrail block. Later entries don't run in that case.
+- An entry can be disabled to keep its configuration without running it.
+  Disabled entries are still validated, so a disabled entry can't reference a
+  policy that's no longer declared.
+- An app with an empty chain runs no app-selected policies; requests go straight
+  to the AI Gateway handler.
+- The chain is inbound-only. An app can't select an outbound policy, and the
+  gateway rejects a chain entry whose declaration is outbound-only. Policies
+  that need the response—Semantic Cache and the Akamai AI Firewall—register a
+  response hook from their inbound position, so one entry covers both
+  directions.
+- There's no allow-list of policy types. Any policy declared in `policies.json`
+  that works as an inbound policy is a valid chain entry, including a
+  [custom code policy](./custom-policies.mdx). The only exclusions are the
+  [Configuration Executor](#configuration-executor) itself and outbound-only
+  policies.
+- Chain validation is all-or-nothing: if any entry is invalid—for example, it
+  references a policy that isn't declared in the gateway's `policies.json`—the
+  request fails with an error identifying the entry to fix, and no entries run.
+  The gateway never guesses.
+
+### Options and secrets
+
+An entry either **inherits** the options declared in `policies.json` or
+**replaces them completely** with its own—options are never merged
+field-by-field. What matters is whether the entry has an `options` key at all:
+an entry with empty options replaces the declared options with an empty object,
+which breaks a policy that has required settings. Omit options entirely to
+inherit.
+
+Keep credentials in the declaration's options and let entries inherit them, so
+the gateway's repository—not app configuration—holds them. See
+[Configure credentials](./custom-policies.mdx#configure-credentials).
+
+## Recommended order
+
+```text
+Model Filtering → Fallback Model → Budgets and Costs → Semantic Cache
+```
+
+- **Model Filtering** first: it accepts or rejects the request and creates the
+  model selection.
+- **Fallback Model** second: it only enriches an existing model selection and
+  never creates one. A chain with Fallback Model but no Model Filtering does
+  nothing at all—the policy logs a warning and passes the request through
+  unchanged. That's also why a fallback can never bypass the filter.
+- **Budgets and Costs** third: it needs the resolved selection so an exceeded
+  budget can activate the quota fallback.
+- **Semantic Cache** after Budgets and Costs: cache hits still count toward
+  request limits.
+
+Tracing policies work well at the end of the chain, so traces reflect the
+request the earlier policies produced.
+
+## Built-in policies
+
+See the [policies overview](./policies/overview.mdx) for every policy an app can
+run, what each one does, and the identifier it needs in `config/policies.json`.
+Any [custom policy](./custom-policies.mdx) declared in the repository appears in
+the Add Policy dialog alongside the built-in ones.
+
+## Configuration Executor
+
+`ai-gateway-configuration-executor-v2-inbound` is the policy that makes the
+two-layer model work. It loads the app's configuration and then runs the app's
+stored inbound chain, instantiating only policies already declared in
+`config/policies.json`. Every scaffolded gateway declares it and puts it on the
+AI Gateway route—that route entry is what gives an app's chain somewhere to run.
+
+Keep it on the **route**, not in an app's chain: it refuses to run itself
+recursively.
+
+Its only option is `cacheTtlSeconds`, which sets how long the gateway caches a
+loaded app configuration. The default is `10` seconds, `10` is also the minimum,
+and a lower value throws a configuration error—as does any other option key. The
+cache is skipped when the [authentication policy](#authentication) already
+loaded the configuration for the request.
+
+## Authentication
+
+The `ai-gateway-auth-v2-inbound` policy—**API Key Authentication** in the
+portal—requires callers to present the app's API key, and it applies per app:
+add it to an app's chain to require a key for that app alone. A new team's
+[policy template](./policy-templates.mdx) includes it as a locked entry, so apps
+created in the team require keys from the start. To require keys for every app
+on a route regardless of what each app's chain selects, put the policy on the
+route in the gateway's repository, before the Configuration Executor.
+
+Where the policy applies, clients send the app's API key as a bearer token and
+the gateway resolves the calling app from the key; for a missing or invalid key
+the gateway returns a `401 Unauthorized`. Its `authHeader` and `authScheme`
+options let the gateway read the key from somewhere other than
+`Authorization: Bearer`—`x-api-key`, for example. The gateway caches key checks
+for `cacheTtlSeconds`, which defaults to 10 seconds, so a revoked key can keep
+working until the cache expires. Each app's key appears on its app page—see
+[Apps](./apps.mdx).
+
+:::caution{title="A gateway without the authentication policy is open"}
+
+When the policy sits neither on the route nor in the app's chain, the gateway
+resolves the app from the `{app_id}` segment of the request URL and serves the
+request with no key of any kind. Anyone who knows the URL can spend against the
+app's providers and budget. Only run an open gateway when something else, such
+as network isolation, controls who can reach it.
+
+:::
+
+## Next steps
+
+- [Custom Policies](./custom-policies.mdx): write your own policy and add it to
+  a chain
+- [Policy Templates](./policy-templates.mdx): seed consistent chains across a
+  team's apps
+- [Usage Limits](./usage-limits.mdx): budgets at the gateway, team, and app
+  levels

package/docs/ai-gateway/policy-templates.mdx

@@ -0,0 +1,68 @@
+---
+title: AI Gateway Policy Templates
+sidebar_label: Policy Templates
+description:
+  Team policy templates give every new app in a team a consistent starting
+  policy chain, with per-policy controls over what each app may change or
+  remove.
+---
+
+A team's **policy template** is the policy chain that apps created in that team
+start with. Use templates to make sure every app in a team begins with your
+required policies—Budgets and Costs with a sensible budget, a guardrail, your
+custom compliance policy—while controlling what individual apps may change.
+
+## How templates apply
+
+When an app is created in a team, the team's template is copied into the app as
+its starting [policy chain](./policy-chains.mdx). From that point on, the chain
+belongs to the app.
+
+A new team's template starts with the **API Key Authentication** policy as a
+locked entry, so every app created in the team requires its API key from the
+start. A new sub-team starts by
+[inheriting its parent's template](#inheriting-from-a-parent-team) instead of
+defining its own.
+
+:::caution{title="Template edits don't change existing apps"}
+
+A template is a starting point, not a live link. Editing a team's template
+affects apps created afterwards—it never changes the chains of the team's
+existing apps. To change a running app's behavior, edit that app's chain on its
+Policies tab.
+
+:::
+
+## Editing a template
+
+Open a team and select its **Policies** tab. The template editor works like the
+app chain editor: add policies from the gateway's declared menu, order them, and
+configure their options.
+
+Each policy in the template carries two checkboxes that control what an app
+starting from the template may do with that entry. Both start checked—a policy
+you add to a template stays locked until you uncheck the boxes:
+
+| Checkbox                                                | When checked                                                        |
+| ------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Cannot edit** (`canEdit: false` in configuration)     | Apps can't change the entry's options—the template's settings apply |
+| **Cannot delete** (`canRemove: false` in configuration) | Apps can't remove the entry from their chain                        |
+
+Locked entries appear in the app's chain with a lock icon and the note "Locked
+by the team policy template".
+
+## Inheriting from a parent team
+
+A sub-team can use its parent team's template instead of defining its own,
+controlled by the **Inherit from parent** switch on the sub-team's Policies tab.
+While inheriting, the sub-team's template is read-only—it shows the parent's
+effective template. Turn the switch off to give the sub-team its own template:
+the editor starts from a copy of the parent's effective template, which you then
+adjust. Turning inheritance back on discards the sub-team's own template in
+favor of the parent's.
+
+## Next steps
+
+- [Policy Chains](./policy-chains.mdx): how an app's chain executes
+- [Managing Teams](./managing-teams.mdx): creating teams and sub-teams
+- [Custom Policies](./custom-policies.mdx): put your own policy in a template

package/docs/ai-gateway/providers.mdx

@@ -1,10 +1,14 @@
 ---
 title: AI Providers
 sidebar_label: Overview
+description:
+  The AI providers and capabilities the Zuplo AI Gateway supports, including
+  OpenAI, Anthropic, Google, Mistral, xAI, and OpenAI-compatible custom
+  providers.
 ---
 
 Zuplo's AI Gateway supports integration with various AI providers, allowing you
-to leverage different models and services for your AI applications.
+to leverage different models and services for your apps.
 
 ## Supported Providers
 
@@ -20,14 +24,24 @@ Zuplo currently supports the following AI providers:
 
 The following capabilities are supported across providers:
 
-| Provider                   | Chat Completions | Text Completions | Embeddings | Responses |
-| -------------------------- | ---------------- | ---------------- | ---------- | --------- |
-| OpenAI                     | ✅               | ✅               | ✅         | ✅        |
-| Anthropic                  | ✅               | ✅               | ✅         | ❌        |
-| Google                     | ✅               | ✅               | ✅         | ❌        |
-| Mistral                    | ✅               | ✅               | ✅         | ❌        |
-| xAI                        | ✅               | ✅               | ✅         | ❌        |
-| OpenAI-compatible (Custom) | ✅               | ✅               | ✅         | ❌        |
+| Provider                   | Chat Completions | Embeddings | Responses | Messages |
+| -------------------------- | ---------------- | ---------- | --------- | -------- |
+| OpenAI                     | ✅               | ✅         | ✅        | ❌       |
+| Anthropic                  | ✅               | ❌         | ❌        | ✅       |
+| Google                     | ✅               | ✅         | ❌        | ❌       |
+| Mistral                    | ✅               | ✅         | ❌        | ❌       |
+| xAI                        | ✅               | ✅         | ❌        | ❌       |
+| OpenAI-compatible (Custom) | ✅               | ✅         | ❌        | ❌       |
+
+**Responses** is the OpenAI Responses API (`/v1/responses`), and **Messages** is
+the native Anthropic Messages API (`/v1/messages`). See the
+[Universal API](./universal-api.mdx#supported-endpoints) for the endpoint each
+capability maps to.
+
+Apps reference a provider's models as `providerName/model`—for example
+`openai/gpt-5-mini` or `anthropic/claude-sonnet-4-6`—where `providerName` is the
+name you give the provider configuration. See the
+[Universal API](./universal-api.mdx).
 
 If you need support for additional providers or capabilities, please contact us
 at [support@zuplo.com](mailto:support@zuplo.com). We're continually working to

package/docs/ai-gateway/source-control.mdx

@@ -0,0 +1,88 @@
+---
+title: AI Gateway Source Control
+sidebar_label: Source Control
+description:
+  Every AI Gateway project deploys from a Git repository you own. Learn what the
+  scaffolded repository contains, how pushes deploy to production, and which
+  changes require a deploy versus applying live.
+---
+
+Every AI Gateway project is backed by a Git repository that you own. The
+repository contains the gateway's routes and policy declarations, so gateway
+changes go through your normal review workflow, and custom policies are plain
+TypeScript files you commit alongside them.
+
+## Connecting a repository
+
+A new AI Gateway project must be connected to a repository before it can deploy.
+Zuplo supports GitHub, GitLab, Bitbucket, and Azure DevOps—see
+[Source Control and Deployment](../concepts/source-control-and-deployment.mdx)
+for what each provider supports.
+
+The project shows a **Let's Get You Deployed** screen with two options:
+
+- **Create New Repo** starts a new repository with the name prefilled. With
+  GitHub, this opens GitHub directly; create the repository, then return to the
+  portal to connect it.
+- Connect an existing repository. Use an empty one so the gateway's source has
+  the repository to itself.
+
+When you connect, Zuplo adds the gateway's source to the repository, pushes it,
+and starts the first production deployment.
+
+:::note
+
+If your default branch requires pull requests, Zuplo pushes the gateway source
+to a setup branch and surfaces a pull request for you to merge. The first
+deployment starts once the pull request lands on the default branch.
+
+:::
+
+## What the repository contains
+
+The scaffolded gateway is a small, readable Zuplo project:
+
+| File                   | Purpose                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `config/ai.oas.json`   | The gateway's route, which the AI Gateway handler serves                        |
+| `config/policies.json` | The menu of policies apps can add to their [policy chains](./policy-chains.mdx) |
+| `zuplo.jsonc`          | Project configuration                                                           |
+| `env.example`          | Example environment variables                                                   |
+| `tsconfig.json`        | TypeScript configuration for custom policy modules                              |
+
+Add custom policy modules under `modules/` and declare them in
+`config/policies.json`—see [Custom Policies](./custom-policies.mdx).
+
+## How deployments work
+
+The repository's default branch is what production runs. With GitHub, every push
+to it deploys automatically. With GitLab, Bitbucket, and Azure DevOps, your own
+CI/CD pipeline deploys by calling `zuplo deploy`—see
+[Source Control and Deployment](../concepts/source-control-and-deployment.mdx).
+
+There is no in-portal code editor for AI Gateway projects—the repository is the
+source of truth, and you edit it with your normal tools.
+
+Three categories of changes take effect differently:
+
+| Change                                                            | Takes effect                                         |
+| ----------------------------------------------------------------- | ---------------------------------------------------- |
+| Repository changes (routes, `policies.json`, custom policy code)  | On the next deploy of the default branch             |
+| App policy chains, teams, budgets, and templates (portal changes) | Within about a minute, no deploy needed              |
+| Provider settings and environment variables                       | Automatically, via a rebuild and deploy Zuplo starts |
+
+:::note
+
+Provider API keys are stored as
+[environment variables](../articles/environment-variables.mdx), so saving
+provider settings or environment variables triggers an automatic production
+deployment.
+
+:::
+
+## Next steps
+
+- [Policy Chains](./policy-chains.mdx): how apps select policies from
+  `config/policies.json`
+- [Custom Policies](./custom-policies.mdx): add your own policy to the
+  repository