zuplo 7.9.14 → 7.9.16

package/docs/articles/environment-variables.mdx

@@ -4,23 +4,44 @@ sidebar_label: Environment Variables
 ---
 
 Environment variables are key-value pairs that are stored outside of source
-code. The values of environment variables can be applied to particular
-environments in order to change behavior or configuration.
+code. Set a different value for each environment to change behavior or
+configuration without changing code.
 
-Environment variables can be read into source code and many configuration files
-in your project. Variables are only applied to environments on new deployments.
-If you change an environment variable, you must redeploy the environment in
-order for the updated value to take effect.
+Variables are only applied to environments on new deployments. If you change an
+environment variable, redeploy the environment for the updated value to take
+effect.
 
-Environment variables can be configuration or secrets. While all values are
-stored encrypted at rest, only non-secret values can be read. Secrets are
-write-only, meaning the value can't be retrieved once it's set.
+Environment variables can be configuration or secrets. All values are stored
+encrypted at rest, but only configuration values can be read back. Secrets are
+write-only: you can't retrieve a secret's value after you set it.
 
-:::tip
+## Gateway and Developer Portal Variables
 
-API Reference For detailed information about accessing environment variables in
-code, see the
-[Environment Variables API Reference](../programmable-api/environment.mdx).
+A Zuplo project has two places that read environment variables: your API gateway
+and your [Developer Portal](../dev-portal/overview.mdx). Both use the variables
+you set in the [editor](#environment-variable-editor), but each one gets a
+different set of variables at a different time.
+
+|                      | API gateway                                                          | Developer Portal                                                                         |
+| -------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Variables available  | All variables, including secrets                                     | Only configuration variables whose names start with `ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_`  |
+| When they're read    | At runtime                                                           | When the portal is built                                                                 |
+| Who can see values   | Only your gateway code                                               | Anyone who visits the portal, because values are embedded in the published site          |
+| How to read them     | `environment.VAR_NAME` in code, `$env(VAR_NAME)` in config files     | `process.env.VAR_NAME` in `zudoku.config.tsx`, `import.meta.env.VAR_NAME` in components  |
+| Variables Zuplo sets | `ZUPLO_ENVIRONMENT_STAGE`, `ZUPLO_ENVIRONMENT_NAME`, and others      | `ZUPLO_ENVIRONMENT_TYPE`, `ZUPLO_SERVER_URL`, and `ZUPLO_BUILD_ID`                       |
+| Reference            | [Gateway environment variables](../programmable-api/environment.mdx) | [Dev Portal environment variables](../dev-portal/zudoku/guides/environment-variables.md) |
+
+Your gateway can also read `ZUPLO_PUBLIC_` and `ZUDOKU_PUBLIC_` variables. Never
+put a secret in a variable with one of these prefixes. Zuplo doesn't send secret
+variables to the Developer Portal build, even if their names have a public
+prefix.
+
+:::caution{title="Same name, different values"}
+
+`ZUPLO_ENVIRONMENT_TYPE` means different things in the gateway and in the
+Developer Portal build. To check whether the code is running in production, use
+`ZUPLO_ENVIRONMENT_STAGE` in your gateway (`production`) and
+`ZUPLO_ENVIRONMENT_TYPE` in your Developer Portal (`PRODUCTION`).
 
 :::
 
@@ -38,7 +59,8 @@ To create a new variable, click **Add variable**.
 </ModalScreenshot>
 
 Enter the name and value of your environment variable and select if you would
-like the value to be a secret or a regular value.
+like the value to be a secret or a regular value. Values take effect on the next
+deployment of each environment.
 
 ## Environments
 
@@ -68,224 +90,27 @@ variable named `MY_VAR` can't be set on say the **Production** environments.
 
 ## Reserved Environment Variables
 
-Environment variables can't start with `ZUPLO_` or `__ZUPLO`. The same
-restriction applies to names beginning with `ZUDOKU_`.
-
-If you need a variable that's exposed to the
-[Developer Portal](../dev-portal/overview.mdx) build, prefix it with
-`ZUPLO_PUBLIC_` (or `ZUDOKU_PUBLIC_`). Public-prefixed variables are bundled
-into the portal's static output and **must not contain secrets**, as they're
-visible to anyone who loads the page.
-
-## Using Environment Variables
-
-Environment variables can be used in several places in your Zuplo project. Each
-location has its own syntax:
-
-| Location                                              | Syntax                 | Resolved              |
-| ----------------------------------------------------- | ---------------------- | --------------------- |
-| Custom code (handlers, policies, hooks)               | `environment.VAR_NAME` | Runtime               |
-| Configuration files (`policies.json`, OpenAPI routes) | `$env(VAR_NAME)`       | Build time            |
-| URL Rewrite, URL Forward, and WebSocket handlers      | `${env.VAR_NAME}`      | Runtime (per request) |
-| Developer Portal config (`zudoku.config.ts`)          | `process.env.VAR_NAME` | Portal build time     |
-
-### In Code
-
-Variables are accessed through the `environment` object from `@zuplo/runtime`.
-See the
-[Environment Variables API Reference](../programmable-api/environment.mdx) for
-detailed usage examples and patterns.
-
-```ts
-import { environment } from "@zuplo/runtime";
-
-const apiKey = environment.API_KEY; // string | undefined
-```
-
-### In Configuration Files
-
-Inside policy options, route handler options, and CORS policy options,
-environment variables can be referenced with the `$env(VAR_NAME)` pattern.
-Substitutions happen at build time — the build replaces each `$env()` expression
-with a reference to the runtime `environment` object before the project is
-deployed.
-
-#### Where `$env()` is allowed
-
-- `config/policies.json` — any property under `policies[].handler.options`,
-  including nested objects and array elements
-- `config/policies.json` — any direct property of a `corsPolicies[]` entry, such
-  as `allowedOrigins`, `allowedHeaders`, `allowedMethods`, `exposeHeaders`, and
-  `maxAge`
-- `config/routes.oas.json` (and other OpenAPI route files) — any property under
-  a route's `x-zuplo-route.handler.options`, including nested objects and array
-  elements
-
-`$env()` is **not** allowed in other locations such as policy `name`,
-`policyType`, `module`, route paths, or top-level OpenAPI fields. Using it
-elsewhere produces a build error:
-
-```text
-An $env() statement is not expected at this location.
-```
-
-#### Standalone substitution
-
-When the value is _only_ an `$env()` expression, the variable's value is
-inserted directly. The runtime type matches the type of the environment variable
-(always a string when set, `undefined` when not).
-
-```json
-{
-  "name": "my-custom-code-inbound-policy",
-  "policyType": "custom-code-inbound",
-  "handler": {
-    "export": "default",
-    "module": "$import(./modules/YOUR_MODULE)",
-    "options": {
-      "apiKey": "$env(BACKEND_API_KEY)",
-      "config2": true
-    }
-  }
-}
-```
-
-#### String interpolation
-
-You can mix `$env()` with literal text to compose a value. The build wraps the
-result in a JavaScript template literal that's evaluated at runtime, so each
-request gets the current value of the variable.
-
-```json
-{
-  "options": {
-    "endpoint": "https://$env(API_HOST)/v1",
-    "userAgent": "MyGateway/$env(APP_VERSION) ($env(ENVIRONMENT_NAME))"
-  }
-}
-```
-
-:::note
-
-If the variable isn't set, the interpolated portion resolves to an empty string.
-For example, with `API_HOST` unset, `"https://$env(API_HOST)/v1"` becomes
-`"https:///v1"`. Use a standalone `$env()` (no surrounding text) if you need to
-detect an unset variable in your handler or policy code.
+Names that start with `ZUPLO_`, `__ZUPLO`, or `ZUDOKU_` are reserved for Zuplo,
+with these exceptions:
 
-:::
+- `ZUPLO_PUBLIC_` and `ZUDOKU_PUBLIC_` are allowed. Use them for values your
+  Developer Portal needs.
+- A few Zuplo settings, such as `ZUPLO_LOG_LEVEL`, are allowed.
 
-#### In arrays
-
-`$env()` works inside string array elements, including mixed arrays where some
-elements are static and others are interpolated:
-
-```json
-{
-  "options": {
-    "allowedKeys": ["$env(PRIMARY_KEY)", "$env(SECONDARY_KEY)"],
-    "tags": ["public", "$env(REGION)", "tier-$env(SERVICE_TIER)"]
-  }
-}
-```
-
-#### In nested objects
-
-`$env()` works at any depth within a handler or policy `options` object:
-
-```json
-{
-  "options": {
-    "database": {
-      "host": "$env(DB_HOST)",
-      "credentials": {
-        "username": "$env(DB_USER)",
-        "password": "$env(DB_PASSWORD)"
-      }
-    }
-  }
-}
-```
-
-#### Variable name rules
-
-The name inside `$env(...)` is matched literally up to the first closing
-parenthesis. Use only letters, digits, and underscores in the name — matching
-what the [Zuplo Portal](#environment-variable-editor) accepts when you create
-the variable.
-
-### Rewrite, Forwarding, and WebSocket Handlers
-
-The URL Rewrite handler's `rewritePattern`, the URL Forward handler's `baseUrl`,
-and the WebSocket handler's `rewritePattern` use a different syntax. These
-options are evaluated as JavaScript template literals at request time, so you
-reference variables with `${env.VAR_NAME}`:
-
-```json
-{
-  "handler": {
-    "export": "urlForwardHandler",
-    "module": "$import(@zuplo/runtime)",
-    "options": {
-      "baseUrl": "https://${env.BACKEND_HOST}"
-    }
-  }
-}
-```
-
-Because `rewritePattern` and `baseUrl` run as code, they also have access to the
-request, URL parts, route params, and query string. See the
-[URL Rewrite Handler](../handlers/url-rewrite.mdx) docs for the full list of
-available variables.
-
-:::caution
-
-Using `$env(VAR_NAME)` inside `rewritePattern` or `baseUrl` is the most common
-mistake. The build will warn you when it detects this, but the value will be
-passed through to the handler as a literal string and the rewrite will fail at
-runtime. Always use `${env.VAR_NAME}` in these two options.
+Use only letters, digits, and underscores in variable names.
 
-:::
+## Local Development
+
+Local development doesn't use the variables you set in the Zuplo Portal. Your
+local gateway reads variables from a `.env` file in your project, and your local
+Developer Portal reads them from a `.env` file in its own folder. See
+[Configuring Environment Variables Locally](./local-development-env-variables.mdx).
+
+## Next Steps
 
-### In the Developer Portal
-
-The Developer Portal's `zudoku.config.ts` runs in Node-like build tooling and
-uses `process.env` rather than `$env()`:
-
-```ts title="zudoku.config.ts"
-const config: ZudokuConfig = {
-  authentication: {
-    type: "auth0",
-    domain: process.env.ZUPLO_PUBLIC_AUTH0_DOMAIN,
-    clientId: process.env.ZUPLO_PUBLIC_AUTH0_CLIENT_ID,
-  },
-};
-
-export default config;
-```
-
-Only variables prefixed with `ZUPLO_PUBLIC_` (or `ZUDOKU_PUBLIC_`) are available
-in the portal build, and their values are embedded into the client-side bundle.
-Don't use this prefix for any value that should remain private.
-
-## System Environment Variables
-
-The following variables are automatically set by the system and are available to
-use in your code:
-
-- `ZUPLO_ENVIRONMENT_TYPE` - The current environment type the API is running.
-  Values are `edge`, `local`.
-- `ZUPLO_ENVIRONMENT_STAGE` - The stage of the environment. Values are
-  `production`, `preview`, `working-copy`, and `local`.
-- `ZUPLO_ENVIRONMENT_NAME` - The name of the environment. This is a globally
-  unique name for the environment. This is the same name that's used in the URL
-  of the environment. For example, `my-project-main-1235.zuplo.app`. Setting a
-  custom domain on the environment won't change this value.
-- `ZUPLO_ACCOUNT_NAME` - The name of the Zuplo account where the environment is
-  deployed.
-- `ZUPLO_PROJECT_NAME` - The name of the project where the environment is
-  deployed.
-- `ZUPLO_BUILD_ID` - The build ID of the environment. This is a unique ID for
-  each build of the environment. This is a UUID.
-- `ZUPLO_COMPATIBILITY_DATE` - The
-  [compatibility date](../programmable-api/compatibility-dates.mdx) of runtime
-  environment.
+- [Gateway environment variables](../programmable-api/environment.mdx): read
+  variables in code, policies, route handlers, and URL rewrites, and the
+  variables Zuplo sets for your gateway.
+- [Dev Portal environment variables](../dev-portal/zudoku/guides/environment-variables.md):
+  read variables in `zudoku.config.tsx` and components, and the variables Zuplo
+  sets when it builds your portal.

package/docs/articles/graphql-support.mdx

@@ -1,21 +1,21 @@
 ---
-title: GraphQL support on Zuplo
-sidebar_label: Overview
+title: Using Zuplo with GraphQL APIs
+sidebar_label: GraphQL overview
 description:
-  Everything Zuplo supports for GraphQL APIs — proxying, security, caching,
-  analytics, Dev Portal docs, and MCP — with links to each guide and policy.
+  Zuplo fully supports GraphQL APIs. Proxy your GraphQL server through the
+  gateway to add auth, rate limiting, caching, and GraphQL-specific policies.
 tags:
   - backends
 ---
 
-Zuplo treats GraphQL as a first-class backend. Proxy your existing GraphQL
-server through the gateway, then layer on security, caching, analytics, and
-documentation using policies built for the GraphQL request shape — where every
-operation is a `POST` to a single URL, so URL-based gateway features don't
-apply.
+**Yes, Zuplo supports GraphQL.** Zuplo is a proxy-based API gateway, and a
+GraphQL API is just an HTTP endpoint — typically a single `POST /graphql` route.
+Proxy your existing GraphQL server through Zuplo, then layer on authentication,
+rate limiting, caching, analytics, and documentation using the same policies you
+use for REST, plus policies built specifically for the GraphQL request shape.
 
-This page summarizes what Zuplo supports for GraphQL and links to each guide and
-policy reference.
+This page summarizes everything Zuplo offers for GraphQL APIs and links to each
+guide and policy reference.
 
 :::tip{title="New here?"}
 
@@ -28,8 +28,9 @@ the gateway, then come back to layer on the capabilities below.
 
 Proxy any GraphQL server through a `POST /graphql` route using the
 [URL Rewrite handler](../handlers/url-rewrite.mdx). The Route Designer ships a
-**GraphQL Endpoint** template, and the `x-graphql` route extension marks a route
-as GraphQL so the gateway and Dev Portal treat it accordingly.
+**GraphQL Endpoint** template, and the `x-graphql` route extension (a boolean
+flag in `routes.oas.json` — set `"x-graphql": true` on the route operation)
+marks a route as GraphQL so the gateway and Dev Portal treat it accordingly.
 
 - [Set up an endpoint](./graphql.mdx) — add or mark a GraphQL route
 
@@ -48,6 +49,20 @@ schema through introspection. Zuplo closes these gaps at the edge.
 - [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
   introspection controls
 
+## Authenticate and rate-limit
+
+Because a GraphQL route is a standard Zuplo route, every general-purpose policy
+works on it — including authentication and rate limiting. Attach an API key auth
+policy or any other auth policy as an inbound policy on the `POST /graphql`
+route, then add a rate limiting policy to protect your upstream from traffic
+spikes. No GraphQL-specific configuration is required; these policies operate on
+the HTTP request before the GraphQL-specific policies run.
+
+- [API key authentication](./api-key-authentication.mdx) — authenticate
+  consumers with API keys
+- [Rate limiting](../rate-limiting/getting-started.mdx) — throttle requests per
+  consumer, IP, or globally
+
 ## Accelerate with caching
 
 A normal CDN keys on the URL, so it can't cache GraphQL queries sent as request
@@ -60,15 +75,18 @@ form, and serves semantically identical queries from one edge cache entry.
 ## Observe traffic
 
 Report GraphQL operations and their errors to analytics, even when the upstream
-returns errors inside a `200` response. The GraphQL analytics dashboard surfaces
-operation volume, latency, and error classes once traffic flows.
+returns errors inside a `200` response (GraphQL servers signal per-field errors
+in the response body rather than with HTTP status codes). The GraphQL analytics
+dashboard surfaces operation volume, latency, and error classes once traffic
+flows.
 
 - [GraphQL analytics](../analytics/tabs/graphql.md) — monitor operations,
   latency, and errors
 
 ## Document in the Dev Portal
 
-The `@zudoku/plugin-graphql` package renders a browsable type reference and an
+The `@zudoku/plugin-graphql` Dev Portal plugin (an npm package included with
+[Zudoku](https://zudoku.dev)) renders a browsable type reference and an
 interactive playground in your Dev Portal, generated from your schema or a live
 endpoint. Register one instance per API.
 
@@ -77,12 +95,35 @@ endpoint. Register one instance per API.
 
 ## Expose GraphQL to AI agents
 
-Turn GraphQL queries into MCP tools so AI agents can call your API through the
-Model Context Protocol, with the same policies and auth applied.
+Turn GraphQL queries into MCP tools — MCP (Model Context Protocol) is a standard
+that lets AI agents discover and call API operations — so AI agents can call
+your GraphQL API with the same policies and auth applied.
 
 - [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose queries as
   MCP tools
 
+## Zuplo and GraphQL federation
+
+Zuplo is a proxy-based API gateway, not a native GraphQL federation gateway. It
+does not perform schema composition, query planning, or subgraph orchestration —
+those are the job of a dedicated federation layer such as Apollo Router or a
+similar tool.
+
+When you use a federated architecture, Zuplo sits **in front of** your
+federation gateway as the public-facing entry point. Traffic flows through Zuplo
+first for authentication, rate limiting, and analytics, then Zuplo forwards the
+request to Apollo Router (or your federation tool of choice), which resolves the
+query across your subgraphs. This layered pattern gives you edge-level security
+and observability without interfering with the federation layer's query
+planning.
+
+```text title="Request flow with federation"
+Client → Zuplo (auth, rate limit, analytics) → Apollo Router → Subgraphs
+```
+
+If your GraphQL API is a single server (no federation), Zuplo connects to it
+directly and no federation layer is needed.
+
 ## Policies at a glance
 
 Every GraphQL-aware policy Zuplo ships, with its direction and purpose:

package/docs/articles/local-development-env-variables.mdx

@@ -3,21 +3,50 @@ title: "Configuring Environment Variables Locally"
 sidebar_label: Environment variables
 ---
 
-For security reasons, your local development doesn't have access to the
-environment variables that you have configured on the Zuplo Portal. Instead,
-your local Zuplo Gateway will load environment variables from a .env file.
+For security reasons, local development doesn't have access to the environment
+variables that you set in the Zuplo Portal. Instead, set them in `.env` files.
 
-1. Create a .env file in the root of your project.
-2. Follow the following format
+Your gateway and your Developer Portal read different files, just as they read
+different variables when deployed. See
+[Gateway and Developer Portal Variables](./environment-variables.mdx#gateway-and-developer-portal-variables).
 
 :::warning
 
-As the `.env` file could contain sensitive information, it shouldn't be
-committed to your version system. Consider adding .env to your .gitignore file.
+`.env` files can contain sensitive information, so don't commit them to source
+control. Add `.env` to your `.gitignore` file.
 
 :::
 
-```txt
+## Gateway Variables
+
+Your local gateway loads environment variables from a `.env` file in the root of
+your project:
+
+```txt title=".env"
 KEY1=VALUE1
 KEY2=VALUE2
 ```
+
+Read them the same way as in a deployed gateway. See
+[Gateway environment variables](../programmable-api/environment.mdx).
+
+When you run `zuplo dev`, `ZUPLO_ENVIRONMENT_STAGE` is `local`.
+
+`zuplo link` writes a `.env.zuplo` file with details about the linked account,
+project, and environment. `zuplo dev` loads it along with `.env`. Don't edit
+`.env.zuplo`; `zuplo link` replaces it each time it runs. Put your own variables
+in `.env`.
+
+## Developer Portal Variables
+
+Your local Developer Portal reads variables from a `.env` file in the portal's
+own folder (usually `docs/`), not from the gateway's `.env` file. As in a
+deployed portal, only variables that start with `ZUPLO_PUBLIC_` or
+`ZUDOKU_PUBLIC_` are available:
+
+```txt title="docs/.env"
+ZUPLO_PUBLIC_AUTH0_DOMAIN=my-tenant.us.auth0.com
+```
+
+See
+[Dev Portal environment variables](../dev-portal/zudoku/guides/environment-variables.md).

package/docs/articles/logging.mdx

@@ -11,6 +11,27 @@ To configure your logging, you need to create a `zuplo.runtime.ts` file in the
 `modules`. The examples below show the content of the file with each of the
 different logging plugins.
 
+## Viewing logs in the portal
+
+Every Zuplo project has a built-in log viewer in the Zuplo Portal that shows
+request logs and messages logged with `context.log`. Open your
+[project](https://portal.zuplo.com/+/account/project/), go to **Observability →
+Logs**, and use the **Environment** filter to choose the environment to view.
+How far back you can search depends on your plan. See
+[Data retention](../analytics/access-and-entitlements.md#data-retention).
+
+The viewer supports time-range presets, drag-to-zoom on the histogram, free-text
+search, and filters for severity, status, method, and route. Live mode streams
+new entries as they arrive and pauses automatically, for example when you select
+a request to inspect it.
+
+Logs are also available at the account scope, so you can debug across every
+project in an account in one place. Open
+[**Observability → Logs**](https://portal.zuplo.com/+/account/observability/logs)
+at the account level, then use the **Project** filter in the sidebar to narrow
+the view to a single project. The account view includes logs only from projects
+where your [role](./accounts/roles-and-permissions.mdx) lets you view logs.
+
 ## Log Integrations
 
 Zuplo offers out-of-the box integrations with many common logging vendors. For

package/docs/articles/opentelemetry.mdx

@@ -276,7 +276,7 @@ Set `ratio` to a constant to use one value everywhere. Zuplo populates
 `ZUPLO_ENVIRONMENT_STAGE`, which reads `working-copy` in your working copy and
 `production`, `preview`, or `local` elsewhere, so local development
 (`zuplo dev`) samples at 10% along with deployed environments. See
-[system environment variables](./environment-variables.mdx#system-environment-variables)
+[system environment variables](../programmable-api/environment.mdx#system-environment-variables)
 for the full list.
 
 By default, traces whose root span ends in an error are exported whatever the

package/docs/cli/source-upgrade.mdx

@@ -7,6 +7,19 @@ sidebar_label: source upgrade
   command="source upgrade"
   description="Updates your project structure to the latest conventions"
   options={[
+  {
+    "name": "type",
+    "type": "string",
+    "description": "Upgrade project scaffolding (api) or preview AI Gateway template additions",
+    "default": "api",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "choices": [
+      "api",
+      "ai-gateway"
+    ]
+  },
   {
     "name": "dir",
     "type": "string",
@@ -16,6 +29,15 @@ sidebar_label: source upgrade
     "deprecated": false,
     "hidden": true,
     "normalize": true
+  },
+  {
+    "name": "apply",
+    "type": "boolean",
+    "description": "Apply verified AI Gateway additions after preview and confirmation",
+    "default": false,
+    "required": false,
+    "deprecated": false,
+    "hidden": false
   }
 ]}
   examples={[
@@ -26,6 +48,14 @@ sidebar_label: source upgrade
   [
     "$0 source upgrade --dir ./my-zuplo-project",
     "Specify the project directory path"
+  ],
+  [
+    "$0 source upgrade --type ai-gateway",
+    "Preview versioned AI Gateway additions without changing files"
+  ],
+  [
+    "$0 source upgrade --type ai-gateway --apply",
+    "Validate, preview, and confirm AI Gateway additions"
   ]
 ]}
   usage="$0 source upgrade [options]"
@@ -33,6 +63,11 @@ sidebar_label: source upgrade
 
 ## Upgrade a source-controlled AI Gateway
 
+An AI Gateway connected to source control doesn't receive new routes and
+policies from the template automatically. See
+[Keep the gateway up to date](../ai-gateway/source-control.mdx#keep-the-gateway-up-to-date)
+for when to run this command and how to deploy the result.
+
 Preview missing AI Gateway v2 endpoints and policies from the template bundled
 with your CLI:
 
@@ -75,3 +110,7 @@ The following global options are available for all commands:
 
 - [`--help`](./global-options.mdx#help)
 - [`--api-key`](./global-options.mdx#api-key)
+
+## Additional resources
+
+- [AI Gateway Source Control](../ai-gateway/source-control.mdx)

package/docs/cli/source-upgrade.partial.mdx

@@ -1,5 +1,16 @@
+---
+additional-resources:
+  - name: AI Gateway Source Control
+    href: ../ai-gateway/source-control.mdx
+---
+
 ## Upgrade a source-controlled AI Gateway
 
+An AI Gateway connected to source control doesn't receive new routes and
+policies from the template automatically. See
+[Keep the gateway up to date](../ai-gateway/source-control.mdx#keep-the-gateway-up-to-date)
+for when to run this command and how to deploy the result.
+
 Preview missing AI Gateway v2 endpoints and policies from the template bundled
 with your CLI:
 

package/docs/concepts/ai-gateway.mdx

@@ -53,7 +53,7 @@ Every app exposes an OpenAI-compatible
 [Universal API](../ai-gateway/universal-api.mdx). Point any SDK that supports a
 custom base URL at the app's gateway URL, send the app's API key as a bearer
 token, and reference models as `providerName/model` (for example
-`openai/gpt-5-mini`). One app can use models from several providers through the
+`openai/gpt-6-luna`). One app can use models from several providers through the
 same endpoint, so switching providers is a configuration change rather than a
 code change.