zuplo 6.70.70 → 6.71.0

package/docs/articles/graphql.mdx

@@ -132,8 +132,10 @@ project's working copy — it only works in projects
 
 1. **Install the plugin**
 
-   In your project's `docs/` folder (where `zudoku.config.tsx` lives), install
-   the plugin:
+   Check `docs/package.json` first — new projects ship with
+   `@zudoku/plugin-graphql` already listed in `dependencies`, so there's nothing
+   to install. Only older projects need to add it. In your project's `docs/`
+   folder (where `zudoku.config.tsx` lives), install the plugin:
 
    ```bash
    npm install @zudoku/plugin-graphql
@@ -141,30 +143,10 @@ project's working copy — it only works in projects
 
    The plugin requires `zudoku` `0.80.1` or newer.
 
-2. **Add a schema**
-
-   Drop a GraphQL schema definition language (SDL) file next to your config:
-
-   ```graphql title="schema.graphql"
-   type Query {
-     product(id: ID!): Product
-   }
-
-   type Product {
-     id: ID!
-     name: String!
-     price: Float!
-   }
-   ```
-
-   Don't have an SDL file handy? Skip this step and introspect a live endpoint
-   at build time with `type: "url"` in the next step — the schema is fetched for
-   you when the portal builds.
-
-3. **Register the plugin**
+2. **Register the plugin**
 
    Import `graphqlPlugin` and add an instance per API. The `path` is where the
-   docs mount, and `input` points at your schema:
+   docs mount, and `input` points at your GraphQL endpoint:
 
    ```tsx title="zudoku.config.tsx"
    import { graphqlPlugin } from "@zudoku/plugin-graphql";
@@ -172,15 +154,12 @@ project's working copy — it only works in projects
    const config = {
      plugins: [
        graphqlPlugin({
-         type: "file",
-         input: "./schema.graphql",
+         type: "url",
+         input: "https://graphql.example.com/api",
          path: "/graphql/ecommerce",
          options: {
            title: "E-Commerce GraphQL API",
            description: "Products, orders, and customers.",
-           playground: {
-             endpoint: "https://my-gateway.example.com/graphql",
-           },
          },
        }),
      ],
@@ -189,18 +168,23 @@ project's working copy — it only works in projects
    export default config;
    ```
 
-   Set `playground.endpoint` to the gateway route from the first half of this
-   guide so readers run real queries through your gateway. With a file-based
-   schema the plugin doesn't know where your API lives — leave the endpoint
-   unset and the reference pages still render, but the playground asks you to
-   configure `options.playground.endpoint` before it can run operations.
+   With `type: "url"`, the schema is fetched via introspection when the portal
+   builds, and the playground sends operations to that same URL by default.
+   Point `input` at the gateway route from the first half of this guide so
+   readers run real queries through your gateway — or keep the playground
+   separate from the schema source with `options.playground.endpoint`.
+
+   Have a GraphQL schema definition language (SDL) file instead of a live
+   endpoint? Use `type: "file"` and set `input` to the file's path (for example
+   `./schema.graphql`). A file-based schema doesn't tell the plugin where your
+   API lives, so also set `options.playground.endpoint` — without it the
+   reference pages still render, but the playground asks for an endpoint before
+   it can run operations.
 
-   With `type: "url"`, set `input` to your GraphQL endpoint's URL instead: the
-   schema is fetched via introspection when the portal builds, and the
-   playground defaults to that same URL. You can register the plugin more than
-   once to document several schemas, each with its own `path`.
+   You can register the plugin more than once to document several schemas, each
+   with its own `path`.
 
-4. **Link it in the navigation**
+3. **Link it in the navigation**
 
    Point a navigation link at the instance's `path`. Set `stack: true` so the
    API's own pages render as a stacked sub-navigation instead of expanding

package/docs/articles/mcp-quickstart-local.mdx

@@ -39,7 +39,8 @@ If you're not familiar with Zuplo, it's recommended to go through
 
 1. Create an **MCP Server**
 
-   On your `routes.oas.json` file, choose **Add** and then **MCP Server**.
+   On your `routes.oas.json` file, choose **Add** and then **Dynamic OpenAPI to
+   MCP Server**.
 
    ![Add Route](../../public/media/mcp-quickstart/add-mcp-route.png)
 

package/docs/articles/mcp-quickstart.mdx

@@ -21,8 +21,12 @@ If you're not familiar with Zuplo, it's recommended to go through the
    Let's import an OpenAPI document. You can download this one here
    [todo-openapi.json](https://download-open-api-main-fae215f.d2.zuplo.dev/todo-openapi).
 
+   <ModalScreenshot size="sm">
+
    ![Import OpenAPI](../../public/media/mcp-quickstart/import-openapi.png)
 
+   </ModalScreenshot>
+
    Select the **Code** tab (1), then choose the `routes.oas.json` file (2) and
    choose **Import OpenAPI** (3).
 
@@ -49,7 +53,8 @@ If you're not familiar with Zuplo, it's recommended to go through the
 
 1. Create an **MCP Server**
 
-   On your `routes.oas.json` file, choose **Add** and then **MCP Server** (3)
+   On your `routes.oas.json` file, choose **Add** and then **Dynamic OpenAPI to
+   MCP Server** (3)
 
    ![Add Route](../../public/media/mcp-quickstart/add-mcp-route.png)
 

package/docs/articles/monetization/api-access.mdx

@@ -52,6 +52,190 @@ curl \
   --header "Authorization: Bearer $ZAPI_KEY"
 ```
 
+## Bucket monetization configuration
+
+Each bucket has an optional `MonetizationConfiguration` that holds bucket-wide
+behavior — multi-subscription support, plan display order, plan-level overrides,
+and the default payment grace period. The configuration is read by the runtime
+and the Developer Portal; it is not stored in OpenMeter.
+
+### Read
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+When no configuration row exists for the bucket, the endpoint returns a default
+body with `multipleSubscriptionsEnabled: false`, an empty `planOrder`, empty
+`planSettings`, and `maxPaymentOverdueDays: 3`.
+
+### Upsert
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --request PUT \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "multipleSubscriptionsEnabled": false,
+  "planOrder": ["free", "starter", "pro", "enterprise"],
+  "planSettings": {
+    "pro": { "visiblePhases": ["default"] }
+  },
+  "maxPaymentOverdueDays": 7
+}
+EOF
+```
+
+| Field                          | Type       | Description                                                                                                                                                                                         |
+| ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `multipleSubscriptionsEnabled` | `boolean`  | Stored on the bucket. Reserved for future multi-subscription rules; today the Developer Portal create-subscription path enforces a single active subscription per customer regardless of this flag. |
+| `planOrder`                    | `string[]` | Ordered list of plan keys; drives pricing-page sort and upgrade/downgrade direction during plan changes                                                                                             |
+| `planSettings`                 | `object`   | Per-plan overrides keyed by plan key. The supported sub-key today is `visiblePhases` — an array of phase keys that should appear on the pricing page                                                |
+| `maxPaymentOverdueDays`        | `integer`  | Bucket-default payment grace period. Must be ≥ 0. Defaults to `3` when not set                                                                                                                      |
+
+The request body must include at least one of these fields. All four fields are
+optional in the request — the upsert preserves any field you don't send.
+
+`planOrder` is consumed when a customer changes plans through the Developer
+Portal: a target plan whose index is greater than or equal to the current plan's
+index is treated as an upgrade (immediate timing); a lower index is treated as a
+downgrade (next-billing-cycle timing). Plans not listed in `planOrder` default
+to upgrade timing.
+
+`maxPaymentOverdueDays` is the lowest-precedence default for the payment grace
+period. See
+[Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation)
+for the full precedence chain (customer metadata → plan metadata → bucket
+configuration → built-in default).
+
+### Delete
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --request DELETE \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+After deletion, GET returns the default body again.
+
+## Stripe setup and billing readiness
+
+Most users connect Stripe through the
+[Zuplo Portal](./stripe-integration.md#connecting-your-stripe-account). For
+automated provisioning — CI scripts, infrastructure-as-code, or self-hosted
+control planes — the same flow is available via these API endpoints.
+
+### Install the Stripe app
+
+Connect a Stripe account to a bucket and create the default billing profile in
+one call:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "apiKey": "rk_test_...",
+  "name": "Stripe Billing Profile",
+  "taxEnabled": false,
+  "taxEnforced": false,
+  "country": "US"
+}
+EOF
+```
+
+The endpoint validates the Stripe key prefix against the bucket's environment:
+
+- Working-copy and preview buckets accept `sk_test_*` or `rk_test_*`
+- Production buckets accept `sk_live_*` or `rk_live_*`
+
+The response returns the installed `appId`. The endpoint fails with a
+`409 Conflict` if a Stripe app is already installed for the bucket.
+
+### Read the current Stripe setup
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+Returns the connected Stripe app summary and the billing profiles linked to it.
+
+### Create an additional billing profile
+
+To attach more billing profiles to the same Stripe app:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe/$STRIPE_APP_ID/billing-profile \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "name": "EU Billing Profile",
+  "taxEnabled": true,
+  "taxEnforced": false,
+  "country": "DE"
+}
+EOF
+```
+
+### Check billing readiness
+
+A lightweight check for tooling that gates deploys on Stripe being connected:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/billing-readiness \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+Response:
+
+```json
+{
+  "hasStripeApp": true,
+  "stripeAppId": "app_01H...",
+  "hasDefaultBillingProfile": true,
+  "defaultBillingProfileId": "bp_01H..."
+}
+```
+
+Use this in setup wizards to gate the UI on whether Stripe is connected.
+
+### Update a connected app
+
+Rotate the Stripe key on an existing app, or update its name and metadata:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/apps/$APP_ID \
+  --request PUT \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "type": "stripe",
+  "name": "Stripe Billing Profile",
+  "secretAPIKey": "rk_test_..."
+}
+EOF
+```
+
+The same key-prefix validation applies — a live key is rejected on a
+non-production bucket and vice versa.
+
 ## API Reference
 
 For complete API operations, see the API Reference documentation:

package/docs/articles/monetization/meters.mdx

@@ -58,10 +58,10 @@ carries the quantity:
 `subject` identifies _who_ consumed the subscription's entitlements on this
 request — typically the API key's consumer name, the end-user id, or another
 stable per-actor identifier. It is **not** the subscription id (use the
-`subscription` field for that) and is not used to route billing. Its purpose is
-to let you break down usage within a subscription so you can see which key,
-user, or agent drove the consumption — a single subscription will commonly emit
-events with many different `subject` values. See
+`subscription` field for that) and does not route billing. Its purpose is to let
+you break down usage within a subscription so you can see which key, user, or
+agent drove the consumption — a single subscription will commonly emit events
+with many different `subject` values. See
 [Monetization Policy](./monetization-policy.md) for how usage is recorded.
 
 :::

package/docs/articles/monetization/monetization-policy.md

@@ -145,7 +145,10 @@ below it:
 
 1. **Customer metadata** — `zuplo_max_payment_overdue_days` on the customer
 2. **Plan metadata** — `zuplo_max_payment_overdue_days` on the plan
-3. **Default** — `3` days
+3. **Bucket configuration** —
+   [`maxPaymentOverdueDays`](./api-access.mdx#bucket-monetization-configuration)
+   on the bucket's monetization configuration
+4. **Default** — `3` days
 
 Set the value to `0` to block requests immediately when payment is overdue.
 

package/docs/articles/monetization/private-plans.md

@@ -99,10 +99,9 @@ Save the returned `id` — you need it to publish and invite users.
 
 :::note
 
-The plan `id` is a 26-character ULID (regex
-`^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$`), separate from the human-friendly
-`key` you set on creation. The publish, invite, and other plan-scoped endpoints
-require the `id`, not the `key`.
+The plan `id` is a 26-character ULID. It's distinct from the human-friendly
+`key` field. Use the `id` (not the `key`) when calling `/publish` and
+`/plan-invites`.
 
 :::
 

package/docs/articles/monetization/stripe-integration.md

@@ -45,6 +45,15 @@ specifically Customers, Checkout Sessions, Customer Portal Sessions, Invoices,
 and Tax Calculations. See
 [What Zuplo creates in Stripe](#what-zuplo-creates-in-stripe) for the full list.
 
+:::tip
+
+To script the connection — for CI, infrastructure-as-code, or self-hosted
+control planes — use the
+[Stripe setup API endpoints](./api-access.mdx#stripe-setup-and-billing-readiness)
+instead of the Portal flow.
+
+:::
+
 ### Test mode vs. live mode
 
 Connect with a Stripe **test** key (`sk_test_...`) first to validate your

package/docs/articles/monetization/subscription-lifecycle.md

@@ -67,8 +67,9 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions \
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "plan": { "key": "pro" },
-    "customerId": "01J9ZX2A8R0K8H6VG2C1A0K3WP"
+    "plan": { "key": "pro", "version": 1 },
+    "customerKey": "user_external_id",
+    "timing": "immediate"
   }'
 ```
 
@@ -216,14 +217,15 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscri
   -H "Content-Type: application/json" \
   -d '{
     "timing": "immediate",
-    "plan": { "key": "enterprise" }
+    "plan": { "key": "enterprise", "version": 1 }
   }'
 ```
 
 `timing` accepts `"immediate"`, `"next_billing_cycle"`, or an RFC 3339
 timestamp. Optional fields include `startingPhase`, `name`, `description`,
-`metadata`, `alignment`, and `billingAnchor`. To preview the proration credit
-before committing, call
+`metadata`, `alignment`, and `billingAnchor`. The response includes both the
+closed-out (`current`) and newly-started (`next`) subscriptions. To preview the
+proration credit before committing, call
 `POST /v3/metering/{bucketId}/subscriptions/{subscriptionId}/change/estimate-credit`
 with the same body.
 
@@ -310,9 +312,7 @@ behavior does not apply.
 curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/cancel \
   -H "Authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
-  -d '{
-    "timing": "next_billing_cycle"
-  }'
+  -d '{ "timing": "next_billing_cycle" }'
 ```
 
 `timing` controls when the cancellation takes effect:
@@ -341,9 +341,10 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscri
   -H "Authorization: Bearer {API_KEY}"
 ```
 
-This removes the pending cancellation. The subscription continues as normal. For
-a subscription whose period has already ended, create a new subscription on the
-same plan instead.
+This removes the pending cancellation. The subscription continues as normal.
+
+If the subscription has already ended, create a new subscription rather than
+restoring the old one.
 
 ## Subscriptions per customer
 

package/docs/articles/monorepo-deployment.mdx

@@ -114,7 +114,9 @@ jobs:
         run: npm install
 
       - name: Deploy to Zuplo
-        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "${{
+          github.ref_name }}"
         env:
           ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
 ```
@@ -171,8 +173,12 @@ jobs:
       - name: Deploy to Zuplo
         id: deploy
         shell: bash
+        env:
+          # The PR's source branch — not the pull/<number>/merge ref that
+          # pull_request events check out
+          ENVIRONMENT: ${{ github.head_ref }}
         run: |
-          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$ENVIRONMENT" 2>&1)
           echo "$OUTPUT"
           DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
           echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
@@ -230,6 +236,18 @@ jobs:
             --wait
 ```
 
+:::caution
+
+The deploy step passes `--environment` with the PR's source branch name
+(`github.head_ref`). Workflows triggered by `pull_request` check out the PR
+merge ref (`refs/pull/<number>/merge`), so without `--environment` the CLI names
+the environment after that ref instead of your branch — and any other deploy of
+the same branch creates a second environment with a different URL. See
+[PR Preview Environments](./ci-cd-github/pr-preview-environments.mdx) for
+details.
+
+:::
+
 ### Secrets and environment variables
 
 Store your Zuplo API key as a GitHub Actions secret:

package/docs/articles/multiple-auth-policies.mdx

@@ -10,8 +10,8 @@ tags:
 
 Sometimes multiple types of authentication are needed on an API. For example, an
 API could support JWT Authentication and API Key authentication or two different
-OAuth providers (for example Azure AD for employees and Auth0 for partners).
-Configuring multiple policies in Zuplo can be done in several ways.
+OAuth providers (for example Microsoft Entra ID for employees and Auth0 for
+partners). Configuring multiple policies in Zuplo can be done in several ways.
 
 ## JWT and API Key Authentication
 

package/docs/articles/openapi.mdx

@@ -15,7 +15,8 @@ this is an OpenAPI document used for routing.
 You can use the Route Designer to build your routes, which will be creating an
 OpenAPI document in the background for you (check it out in the **JSON View**).
 
-You can also **import an OpenAPI** document by clicking the **Open API** tab.
+You can also **import an OpenAPI** document by clicking the **Import** button in
+the Route Designer.
 
 ![Import Open API](../../public/media/open-api/image-1.png)
 
@@ -39,8 +40,12 @@ document and will keep your Zuplo settings intact, while overwriting everything
 else from your imported OpenAPI docs. This creates a great workflow, whatever
 toolset you use.
 
+<ModalScreenshot>
+
 ![Import OpenAPI dialog](../../public/media/open-api/28512107-8c41-4974-8319-c9ec50734331.png)
 
+</ModalScreenshot>
+
 What's more, you can now have more confidence that your OpenAPI represents the
 truth of your API implementation - because it now drives the configuration of
 your gateway.

package/docs/articles/rename-or-move-project.mdx

@@ -23,8 +23,12 @@ disconnect the project from Source Control.
 Next create a new project in the correct account if moving accounts or with the
 correct name. Choose the `Advanced` option on the new project dialog.
 
+<ModalScreenshot>
+
 ![Import existing project](../../public/media/source-control/image-1.png)
 
+</ModalScreenshot>
+
 You should see a list of organizations and repositories - pick the source
 repository you wanted to move and click **Create Project from repository**.
 

package/docs/articles/securing-your-backend.mdx

@@ -29,8 +29,12 @@ Open the **Settings** section of your project and select **Environment
 Variables**. Create a new variable and name it `BACKEND_SECRET`. Set the value
 to a secure, random value. Ensure that the value is marked as a secret.
 
+<ModalScreenshot>
+
 ![Set Environment Variable](../../public/media/securing-backend-shared-secret/image.png)
 
+</ModalScreenshot>
+
 ### Step 2: Create a set header policy
 
 Create a policy that sets the `BACKEND_SECRET` as a header on the request to
@@ -40,8 +44,12 @@ is sent to your backend.
 Navigate to the route you want to secure and add a new policy. Select the **Add
 or Set Request Headers** policy type and configure it as follows:
 
+<ModalScreenshot>
+
 ![Set Header Policy](../../public/media/securing-backend-shared-secret/image-1.png)
 
+</ModalScreenshot>
+
 The configuration uses the environment variable via the `$env(BACKEND_SECRET)`
 selector as shown below.
 
@@ -98,10 +106,10 @@ interested in using this option please contact us at `support@zuplo.com`.
 Utilize the IAM controls provided by your Cloud host to secure inbound requests
 and allow only authorized service principals access to your service.
 
-- For Azure users, you can user our
+- For Azure users, you can use the
   [Upstream Azure AD Service Auth](../policies/upstream-azure-ad-service-auth-inbound.mdx)
-  policy. This uses Azure AD App registrations to create a token that Zuplo will
-  send to requests to Azure.
+  policy. This uses Microsoft Entra ID (formerly Azure AD) App registrations to
+  create a token that Zuplo sends with requests to Azure.
 
 - For GCP users, you can use our
   [Upstream GCP Service AUth](../policies/upstream-gcp-service-auth-inbound.mdx)

package/docs/articles/source-control-setup-github.mdx

@@ -130,8 +130,12 @@ If you have an existing GitHub repository that contains a Zuplo project, you can
 connect to that repository when you create a new project. Select **Import
 existing project** then select your GitHub organization and repository.
 
+<ModalScreenshot>
+
 ![Import existing project to Zuplo](../../public/media/source-control/image-1.png)
 
+</ModalScreenshot>
+
 ## What's Included
 
 With GitHub connected, you get:

package/docs/articles/troubleshooting-slow-responses.mdx

@@ -226,8 +226,8 @@ period of inactivity is slow. Subsequent requests are fast.
 
 ### Analytics Dashboard
 
-Zuplo's analytics dashboard provides at-a-glance visibility into your API's
-performance. Use it to:
+Zuplo's analytics dashboard, in the **Observability** tab of your project,
+provides at-a-glance visibility into your API's performance. Use it to:
 
 - Identify slow endpoints by reviewing request latency data
 - Filter by route, API key, or time period to isolate patterns

package/docs/articles/troubleshooting.md

@@ -177,9 +177,9 @@ const response = await fetch("https://api.example.com/data", {
 ### Portal live logs
 
 The Zuplo Portal provides real-time log viewing for deployed environments. Open
-the [**Environments**](https://portal.zuplo.com/+/account/project/environments)
-tab in your project, select the deployed environment, and open the logs tab to
-see live request logs and any messages logged with `context.log`.
+the **Observability** tab in your project — the **Logs** view opens by default —
+then use the **Environment** filter to select the deployed environment and see
+live request logs and any messages logged with `context.log`.
 
 ### Using context.log
 

package/docs/cli/deploy.mdx

@@ -122,6 +122,38 @@ zuplo deploy --project my-project
 zuplo deploy --project my-project --environment my-env-name
 ```
 
+### Deploying from CI/CD
+
+Without `--environment`, the CLI names the environment after the current git
+branch. CI systems usually check out a detached HEAD, in which case the CLI
+resolves the branch from the remote branches that contain the checked-out
+commit. Two cases break this inference:
+
+- On GitHub Actions `pull_request` events, the checkout is the pull request
+  merge ref (`refs/pull/<number>/merge`) — a commit that doesn't exist on any
+  branch — so the environment is named after that ref instead of your branch.
+- When the checked-out commit exists on more than one branch, the first match
+  wins, which may not be the branch that triggered the build.
+
+Always pass `--environment` explicitly in CI so that every trigger deploys the
+same, predictably named environment:
+
+```bash
+# GitHub Actions: github.head_ref is the source branch on pull_request
+# events; github.ref_name is the branch on push events
+zuplo deploy --project my-project --environment "$BRANCH_NAME"
+```
+
+Deploying the same environment name always updates the same environment and
+keeps its URL stable across deploys. This matters whenever an external system
+must match the URL exactly — an OIDC token audience, a webhook registration, or
+an allowlist. Capture the URL from the deploy output (`Deployed to
+https://...`) rather than constructing it from the branch name: the URL
+hostname uses a normalized, truncated form of the environment name plus a
+unique identifier. See
+[Branch-Based Deployments](../articles/branch-based-deployments.mdx) for the
+naming rules.
+
 ## Polling timeout
 
 By default, the deploy command polls the status of the deployment every second