zuplo 7.6.4 → 7.6.5

package/docs/ai-gateway/getting-started.mdx

@@ -98,17 +98,17 @@ account, Zuplo project, and AI Gateway team roles control access.
 
 4. **Create a team**
 
-   Teams organize users and carry hierarchical budget controls and policy
-   templates. Even if you're starting solo, you need at least one team.
+   Teams organize users and carry their own budget rules and policy templates.
+   Even if you're starting solo, you need at least one team.
 
    Open the **Apps & Teams** tab and click **New Team**. Name your team (for
    example, "Root" or your company name), choose an icon, and click **Create
    Team**. This is your first team, so there's no parent picker yet—it appears
    on later teams, letting you nest them. To set gateway-wide spending limits
-   across this Zuplo project, open the gateway's **Settings → Usage Limits**;
-   for team-specific limits, use the team's **Usage & Limits** tab. See
-   [Usage Limits](./usage-limits.mdx). Gateway and team limits apply to every
-   app regardless of its policy chain.
+   across this Zuplo project, open the gateway's **Settings → Usage Limits**.
+   Team budgets—shared and per-expression—are set on the team's **Usage &
+   Limits** tab. See [Usage Limits](./usage-limits.mdx). Gateway and team limits
+   apply to every app regardless of its policy chain.
 
 5. **Create an app**
 

package/docs/ai-gateway/managing-teams.mdx

@@ -41,8 +41,9 @@ After creating a team, use its tabs to configure it:
 
 - **Policy Template**—the team's [policy template](./policy-templates.mdx), the
   starting policy chain for apps created in the team.
-- **Usage & Limits**—spending limits that apply to all of the team's apps
-  combined. See [Usage Limits](./usage-limits.mdx).
+- **Usage & Limits**—the team's budgets, shared and per-expression, applying to
+  the team, its sub-teams, and their apps. See
+  [Usage Limits](./usage-limits.mdx).
 - **Members**—who belongs to the team.
 
 ## Adding Team Members

package/docs/ai-gateway/overview.mdx

@@ -30,9 +30,9 @@ Google, Mistral, xAI, and more) dynamically without modifying app code.
 Configure model access through the gateway rather than hard coding it into your
 apps.
 
-**Cost Control**: Set spending limits at gateway, team, and app levels with
-hierarchical budgets that cascade down through your structure. Configure daily
-and monthly thresholds with enforcement or warning notifications.
+**Cost Control**: Set independent spending limits at the gateway, team, and app
+levels. Configure hourly, daily, weekly, or monthly rules that warn or block
+when usage reaches a limit.
 
 **Security & Compliance**: Apply guardrails to detect and block prompt injection
 attempts and prevent PII leakage in both requests and responses through
@@ -99,13 +99,14 @@ a consistent starting pipeline. See [Policy Chains](./policy-chains.mdx) and
 
 ### Team Hierarchy & Budgets
 
-Organize users into teams with hierarchical structures. Set budget limits at
-each level that cascade down:
+Organize users into teams with hierarchical structures. Set a budget at each
+node. Each node totals its own usage and all descendant usage, and any exceeded
+**Block** limit rejects the request:
 
-- **Gateway**: Limits across the Zuplo project (for example, $1,000/day)
-- **Teams**: Team-specific limits that can't exceed parent limits (for example,
-  $500/day for the Credit Team)
-- **Apps**: Per-app limits for granular control
+- **Gateway**: Limits across the Zuplo project (for example, $1,000/day).
+- **Teams**: Limits across the team, its sub-teams, and their apps (for example,
+  $500/day for the Credit Team).
+- **Apps**: Limits for one app's traffic.
 
 See [Usage Limits](./usage-limits.mdx).
 

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

@@ -34,11 +34,17 @@ Policies tab.
 
 :::
 
+Everything on the **Policy Template** tab is template content, budgets included:
+a **Budgets and Costs** entry in the template sets the default budget each new
+app starts with in its own chain, and doesn't enforce anything on the team. The
+team's own budgets—shared and per-expression—live on the team's **Usage &
+Limits** tab. See [Usage Limits](./usage-limits.mdx).
+
 ## 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.
+Open a team and select its **Policy Template** 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
@@ -55,14 +61,14 @@ 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.
-The switch drafts like the page's other edits and applies when you click **Save
-changes**. 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 and saving discards the
-sub-team's own template in favor of the parent's—before you save, flip the
-switch again to restore your draft.
+controlled by the **Inherit from parent** switch on the sub-team's **Policy
+Template** tab. The switch drafts like the page's other edits and applies when
+you click **Save changes**. 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 and
+saving discards the sub-team's own template in favor of the parent's—before you
+save, flip the switch again to restore your draft.
 
 ## Next steps
 

package/docs/ai-gateway/teams.mdx

@@ -18,7 +18,7 @@ on that member's role.
 
 Teams also carry a [policy template](./policy-templates.mdx)—the policy chain
 that apps created in the team start with—and [usage limits](./usage-limits.mdx)
-that apply to all of the team's apps combined.
+that apply to the team's own usage and all descendant sub-teams and apps.
 
 ## Members
 

package/docs/ai-gateway/usage-limits.mdx

@@ -12,55 +12,94 @@ gateway, team, and app levels.
 
 ## Budget Hierarchy
 
-Limits at every level apply together—a request is blocked when _any_ level's
-limit is exceeded, and the error names whether the whole application or the
-caller's own segment ran out:
+Limits at every level apply together. A request is blocked when the gateway, an
+ancestor team, or the app is over a **Block** limit. The error identifies
+whether a shared node budget or an expression-specific budget ran out:
 
 - **Gateway** - Limits across the Zuplo project (for example, $1,000/day),
-  covering all teams and apps combined
-- **Teams** - Team-specific limits covering all of the team's apps combined (for
-  example, $500/day for the Engineering team)
+  covering all teams, sub-teams, and apps combined
+- **Teams** - Limits covering the team's own usage and every descendant sub-team
+  and app (for example, $500/day for the Engineering team)
 - **Apps** - Per-app limits for granular control (for example, $10/day for a
   hackathon app)
 
+Budgets at different levels don't constrain each other's values, and app budgets
+under a team may add up to more than the team's own budget - the team's budget
+is the aggregate cap. For example, take a $100/month team containing a $50/month
+sub-team with two apps capped at $25/month and $40/month. When the apps have
+spent $40 and $10, the sub-team's aggregate reaches $50 and requests through
+**both** apps are blocked - including the app that is still under its own $25
+cap. Apps elsewhere in the $100/month team keep working until that team's own
+aggregate reaches $100.
+
+<Diagram direction="vertical" height="h-96">
+  <DiagramNode id="team" variant="green">
+    Team · spent $50 of $100
+  </DiagramNode>
+  <DiagramNode id="subteam" variant="red">
+    Sub-team · spent $50 of $50
+  </DiagramNode>
+  <DiagramNode id="appa" variant="red">
+    App A · spent $10 of $25
+  </DiagramNode>
+  <DiagramNode id="appb" variant="red">
+    App B · spent $40 of $40
+  </DiagramNode>
+  <DiagramNode id="other" variant="green">
+    Other apps in the team
+  </DiagramNode>
+  <DiagramEdge from="team" to="subteam" label="at its Block limit" />
+  <DiagramEdge from="team" to="other" label="still serving" />
+  <DiagramEdge from="subteam" to="appa" label="blocked — under its own cap" />
+  <DiagramEdge from="subteam" to="appb" label="blocked" />
+</Diagram>
+
 ## Where limits are configured
 
-| Level   | Where                                                                             | Per-metadata budgets |
-| ------- | --------------------------------------------------------------------------------- | -------------------- |
-| Gateway | **Settings → Usage Limits**                                                       | No                   |
-| Team    | The team's **Usage & Limits** tab                                                 | No                   |
-| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) | Yes                  |
+| Level   | Shared budget                                                                     | Per-expression budgets                                       |
+| ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Gateway | **Settings → Usage Limits**                                                       | Supported in configuration, but not authorable in the Portal |
+| Team    | The team's **Usage & Limits** tab                                                 | The team's **Usage & Limits** tab                            |
+| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) | The **Budgets and Costs** policy                             |
 
-Gateway and team limits are inherited: they apply to every app beneath them,
-whether or not the app's chain includes Budgets and Costs. An app's own limits
-live on that policy, which is also the only place you can budget per metadata
-value.
+Gateway and team limits apply independently to every descendant app; they aren't
+copied into the app's configuration. Each node meters its own usage plus all
+descendant usage. A request is blocked if any node in its path is over a
+**Block** limit. An app's own limits live on the Budgets and Costs policy.
 
 :::note
 
-A team's **Policy Template** tab also carries a **Budgets and Costs** policy.
-That template seeds the policy chain of apps created in the team—it sets those
-apps' limits, not the team's own. Use **Usage & Limits** to cap the team.
+Everything a team enforces lives on its **Usage & Limits** tab. The **Policy
+Template** tab is only the template: a Budgets and Costs entry there is copied
+into each new app as the app's own starting budget and doesn't enforce the
+team's budget.
 
 :::
 
 ## How a budget rule works
 
-An app's budgets are a list of rules on the **Budgets and Costs** policy. Each
-rule answers two questions—what it budgets, and what the caps are.
+Every node's budgets are a list of rules. Each rule answers two questions—what
+it budgets, and what the caps are.
 
 **Scope** decides who shares the budget:
 
-| Scope           | What it budgets                                             |
-| --------------- | ----------------------------------------------------------- |
-| **This app**    | One shared budget for all of the app's traffic              |
-| **By metadata** | A separate budget for every distinct value of an expression |
+| Scope                                      | What it budgets                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| **Shared** (`budgetBy: "app"`)             | One shared budget for the gateway, team, or app and its descendants      |
+| **By metadata** (`budgetBy: "expression"`) | A separate budget at that node for every distinct value of an expression |
+
+A **By metadata** rule gives each distinct expression value its own allowance.
+With the expression `request.headers.get("x-user")` and a $5 daily cap, every
+distinct `x-user` value gets its own $5 per day—one user exhausting their budget
+doesn't affect anyone else. A node can combine a shared rule with several
+expression rules.
 
-A **By metadata** rule gives each caller its own allowance. With the expression
-`request.headers.get("x-user")` and a $5 daily cap, every distinct `x-user`
-value gets its own $5 per day—one user exhausting their budget doesn't affect
-anyone else. An app has a single shared budget, and can add several metadata
-rules alongside it.
+Ancestor rules of both kinds apply to every request through the node's subtree.
+The difference is who gets blocked: a team's **Shared** rule blocks all of the
+team's traffic once the team's aggregate is over, while a team's **By metadata**
+rule meters each value across all of the team's apps combined and blocks only
+the exhausted value—the same `x-user` shares one budget whether it calls App A
+or App B.
 
 **Limit rows** set the caps. Each row is a meter, a period, an amount, and an
 action:
@@ -108,8 +147,9 @@ doesn't reset the period's usage.
 
 </Stepper>
 
-Rules set on a parent team or on the gateway appear in the editor under
-**Inherited**. Edit those where they were created.
+The app editor groups gateway and ancestor team rules under **Inherited**. Those
+rules remain stored and enforced at the gateway or team; edit them where they
+were created.
 
 ### Budget expressions
 
@@ -140,22 +180,32 @@ but budget separately.
 
 :::
 
-To write rules by hand in `config/policies.json` or a
-[policy template](./policy-templates.mdx), see the
+App rules are stored in `options.budgetRules` on the app's own Budgets and Costs
+policy entry. For the app rule schema, see the
 [Budgets and Costs policy reference](../policies/ai-gateway-metering-v2-inbound.mdx).
 
 ## Setting team and gateway limits
 
-Team and gateway limits cover everything beneath them, and apply to every app
-whether or not its chain includes Budgets and Costs.
+Team and gateway limits cover the node's own usage and all descendant usage.
+They apply to every descendant app whether or not its chain includes Budgets and
+Costs.
+
+Team rules—shared and per-expression—are added on the team's **Usage & Limits**
+tab, using the same meter, period, amount, and action rows as the app editor.
+
+To add a shared gateway rule, open **Settings → Usage Limits**. The gateway root
+supports per-expression rules in `metadata.budgetRules`, but the Portal doesn't
+author them. It displays a stored expression rule as read-only and lets you
+delete it.
 
-Both use the same editor as an app, with the same limit rows—meter, period,
-amount, and action. Open the team's **Usage & Limits** tab, or **Settings →
-Usage Limits** for the gateway, then **Add rule** and **Add limit**.
+Each `budgetBy: "app"` rule is a shared budget for the node where the rule is
+stored. At the gateway or team level, `app` means that gateway or team node, not
+an app policy configuration. A team's usage includes its sub-teams and apps, and
+the gateway's usage includes the whole project.
 
-Each level takes one shared budget covering everything beneath it: a team's caps
-all of its apps combined, and the gateway's caps the whole project. Rules set
-higher up appear under **Inherited**—edit those where they were created.
+Gateway and team rules are stored in `metadata.budgetRules` on that node. The
+editor groups ancestor rules under **Inherited**, but each rule remains enforced
+at the node where it was created.
 
 ## When a limit is exceeded
 
@@ -184,9 +234,10 @@ Without a fallback, the request is rejected with `429 Too Many Requests` and a
 }
 ```
 
-The `scope` tells the caller which budget they hit: `application` when a shared
-budget ran out, or `dimension` when their own segment did—two situations with
-different remedies. Quote the `ruleId` when raising a support request.
+The `scope` tells the caller which budget they hit. It is `application` when the
+gateway, a team, or the app exhausts a shared node budget. It is `dimension`
+when a value exhausts an expression budget. Quote the `ruleId` when raising a
+support request.
 
 :::caution{title="Budgets fail open by default"}
 

package/docs/articles/api-key-administration.mdx

@@ -13,8 +13,8 @@ environments.
 ![The API Keys → Consumers page in the Services section, with the sidebar showing API Keys, Monetization, and Audit Logs, and the environment switcher set to Dev](../../public/media/api-key-administration/services-page.png)
 
 To view the bucket for a different environment, use the **Dev / Preview / Prod**
-switcher at the top of the sidebar. Click **Bucket Details** under the **API Key
-Service** heading to copy the active bucket's name or ID.
+switcher at the top of the sidebar. Copy the active bucket's ID from the
+**Bucket ID** pill under the **API Key Service** heading.
 
 To add a new API Key Consumer, click **Create Consumer** and complete the form.
 

package/docs/articles/api-key-api.mdx

@@ -84,12 +84,33 @@ inside Zuplo)
 ```bash
 # Your Zuplo Account Name
 export ACCOUNT_NAME=my-account
-# Your bucket name (Found in Services > API Key Service)
-export BUCKET_NAME=my-bucket
+# Your bucket ID (Found in Services > API Keys > Consumers)
+export BUCKET_ID=bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL
 # Your Zuplo API Key (Found in Account Settings > Zuplo API Keys)
 export API_KEY=zpka_YOUR_API_KEY
 ```
 
+For more information about finding the bucket ID, see
+[Bucket identifiers](./api-key-buckets.mdx#bucket-identifiers).
+
+<details>
+<summary>Legacy: identifying a bucket by name (deprecated)</summary>
+
+The consumer, key, and manager endpoints also accept a bucket name in place of
+the bucket ID, so existing scripts keep working:
+
+```bash
+export BUCKET_NAME=my-bucket
+curl \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers \
+  --header "Authorization: Bearer $API_KEY"
+```
+
+The Zuplo Portal doesn't display bucket names, so use the bucket ID in new code.
+When a value matches both a bucket name and a bucket ID, the name wins.
+
+</details>
+
 ### Creating a Consumer with a Key
 
 When creating a new Consumer, it's a good idea to include some useful metadata
@@ -101,7 +122,7 @@ external identifier that links this consumer to your internal data as a tag.
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers?with-api-key=true \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers?with-api-key=true \
   --request POST \
   --header "Content-type: application/json" \
   --header "Authorization: Bearer $API_KEY" \
@@ -156,7 +177,7 @@ You can use this API Key to call your Zuplo Gateway that's protected by the
 ```shell
 export ORG_ID=1234
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/?include-api-keys=true&key-format=visible&tag.orgId=$ORG_ID \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers/?include-api-keys=true&key-format=visible&tag.orgId=$ORG_ID \
   --header "Authorization: Bearer $API_KEY"
 ```
 
@@ -248,7 +269,7 @@ creates a new key without an expiration.
 export ORG_ID=1234
 export CONSUMER_NAME=my-consumer
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key?tag.orgId=$ORG_ID \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers/$CONSUMER_NAME/roll-key?tag.orgId=$ORG_ID \
   --request POST \
   --header "Authorization: Bearer $API_KEY" \
   --header "Content-Type: application/json" \

package/docs/articles/api-key-authentication.mdx

@@ -144,7 +144,7 @@ development.
 Either locally or in CI/CD you can specify any API Key bucket on the
 [API Key Authentication](../policies/api-key-inbound.mdx) policy by setting the
 `bucketId` property. Every environment can then share a single bucket that holds
-the consumers your tests need. Find a bucket's ID under **Bucket Details** on
+the consumers your tests need. Find a bucket's ID on the **Bucket ID** pill on
 the
 [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
 page in the Zuplo Portal. You can use the

package/docs/articles/api-key-buckets.mdx

@@ -21,6 +21,31 @@ Zuplo automatically creates three buckets for each project:
 For more information on how environments relate to Git branches, see
 [Branch-Based Deployments](./branch-based-deployments.mdx).
 
+## Bucket identifiers
+
+Every bucket has an ID that starts with `bckt_`, and a name. Use the bucket ID
+whenever you identify a bucket, both in the
+[Zuplo Developer API](./api-key-api.mdx) and in policy configuration. To copy
+it, open
+[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
+in the Zuplo Portal and select the environment with the **Dev / Preview / Prod**
+switcher. The **Bucket ID** pill sits beside the environment badge under the
+**API Key Service** heading, with a copy button.
+
+:::caution{title="Deprecated"}
+
+The bucket name is a legacy identifier. The Zuplo Portal doesn't display it, and
+the Developer API accepts it only for backward compatibility on the consumer,
+key, and manager endpoints. Pass the bucket ID instead.
+
+Three endpoints are the exception and still require the bucket name:
+
+- `GET /v1/accounts/{accountName}/key-buckets/{bucketName}`
+- `PATCH /v1/accounts/{accountName}/key-buckets/{bucketName}`
+- `DELETE /v1/accounts/{accountName}/key-buckets/{bucketName}`
+
+:::
+
 ## Custom bucket configuration
 
 To use a custom bucket, specify its `bucketId` in your API Key policy options:
@@ -36,10 +61,8 @@ To use a custom bucket, specify its `bucketId` in your API Key policy options:
 }
 ```
 
-Bucket IDs start with `bckt_`. To find one, open
-[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
-in the Zuplo Portal, select the environment with the **Dev / Preview / Prod**
-switcher, then click **Bucket Details**.
+For more information about finding a bucket ID, see
+[Bucket identifiers](#bucket-identifiers).
 
 When the configuration sets no bucket, the policy uses the default bucket for
 the current environment.

package/docs/articles/api-key-consumer-bucket-portal-ui.mdx

@@ -65,20 +65,20 @@ For deeper detail, see [Buckets and Environments](./api-key-buckets.mdx).
 1. Use the **Dev / Preview / Prod** switcher at the top of the sidebar to select
    the environment whose bucket you want.
 
-1. Click **Bucket Details** under the **API Key Service** heading to see the
-   active bucket's name and ID, each with a copy button.
+1. Copy the active bucket's ID from the **Bucket ID** pill beside the
+   environment badge under the **API Key Service** heading.
 
 </Stepper>
 
 <ModalScreenshot size="md">
 
-![The API Keys → Consumers page with the environment switcher set to Dev and the Bucket Details button under the API Key Service heading](../../public/media/api-key-consumer-bucket-portal-ui/services-page-dropdown.png)
+![The API Keys → Consumers page with the environment switcher set to Dev and the Bucket ID pill under the API Key Service heading](../../public/media/api-key-consumer-bucket-portal-ui/services-page-dropdown.png)
 
 </ModalScreenshot>
 
-**Bucket Details** shows the name and ID of the bucket that's currently active
-for the selected environment. Bucket IDs start with `bckt_` — this is the value
-the API Key Authentication policy's `bucketId` option takes.
+The **Bucket ID** pill shows the ID of the bucket that's currently active for
+the selected environment. Bucket IDs start with `bckt_` — this is the value the
+API Key Authentication policy's `bucketId` option takes.
 
 ## Create a consumer in a specific bucket
 
@@ -157,7 +157,7 @@ the [Zuplo Developer API](./api-key-api.mdx):
 
 ```bash
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers?with-api-key=true \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers?with-api-key=true \
   --request POST \
   --header "Content-type: application/json" \
   --header "Authorization: Bearer $ZAPI_KEY" \
@@ -168,10 +168,12 @@ curl \
   }'
 ```
 
-Replace `$ACCOUNT_NAME` with your Zuplo account name, `$BUCKET_NAME` with the
-target bucket name, and `$ZAPI_KEY` with your
-[Zuplo API key](./accounts/zuplo-api-keys.mdx). Full reference at the
-[Developer API documentation](https://dev.zuplo.com/docs).
+Replace `$ACCOUNT_NAME` with your Zuplo account name, `$BUCKET_ID` with the
+target bucket's ID, and `$ZAPI_KEY` with your
+[Zuplo API key](./accounts/zuplo-api-keys.mdx). The bucket name also works here,
+but it's deprecated. For more information, see
+[Bucket identifiers](./api-key-buckets.mdx#bucket-identifiers). Full reference
+at the [Developer API documentation](https://dev.zuplo.com/docs).
 
 ## Troubleshooting
 

package/docs/articles/api-key-leak-detection.mdx

@@ -64,12 +64,12 @@ their integration, or omit it to revoke the old key immediately.
 
 ```bash
 export ACCOUNT_NAME="your-account-name"
-export BUCKET_NAME="your-bucket-name"
+export BUCKET_ID="your-bucket-id"
 export CONSUMER_NAME="your-consumer-name"
 export ZUPLO_API_KEY="your-zuplo-api-key"
 
 curl --request POST \
-  --url https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key \
+  --url https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers/$CONSUMER_NAME/roll-key \
   --header 'Authorization: Bearer $ZUPLO_API_KEY' \
   --header 'Content-Type: application/json' \
   --data '

package/docs/articles/api-key-self-serve-integration.mdx

@@ -51,12 +51,12 @@ Before you start, you need:
   under
   [**Account Settings → Zuplo API Keys**](https://portal.zuplo.com/+/account/settings/api-keys).
   [More information](./accounts/zuplo-api-keys).
-- Your **account name** and **bucket name**. A bucket groups consumers for an
+- Your **account name** and **bucket ID**. A bucket groups consumers for an
   environment - each project has buckets for production, preview, and
-  development. Find the bucket name on your project's
+  development. Copy the bucket ID from the **Bucket ID** pill next to the **API
+  Key Service** heading on your project's
   [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
-  page (under **Bucket Details**, next to the **API Key Service** heading), and
-  the account name in
+  page, and the account name from
   [**Project Settings → General**](https://portal.zuplo.com/+/account/project/settings/general).
 - An application with server-side code and existing user authentication.
 
@@ -65,8 +65,8 @@ All examples in this guide use these environment variables:
 ```bash
 # Your Zuplo Account Name
 export ZUPLO_ACCOUNT=my-account
-# Your bucket name (found on the Services → API Keys → Consumers page)
-export ZUPLO_BUCKET=my-bucket
+# Your bucket ID (found on the Services → API Keys → Consumers page)
+export ZUPLO_BUCKET_ID=bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL
 # Your Zuplo API Key (found in Account Settings > Zuplo API Keys)
 export ZUPLO_API_KEY=zpka_YOUR_API_KEY
 ```
@@ -128,7 +128,7 @@ initial API key in a single call by passing `?with-api-key=true`:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers?with-api-key=true \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers?with-api-key=true \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -189,7 +189,7 @@ To render an "API Keys" page in your settings, fetch the consumer's keys:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/keys?key-format=masked \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/keys?key-format=masked \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 ```
 
@@ -224,7 +224,7 @@ staging and production), create a key directly:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/keys \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/keys \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -238,7 +238,7 @@ the user a transition period to switch over. Use the roll-key endpoint:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/roll-key \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/roll-key \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -261,7 +261,7 @@ To let users revoke a specific key immediately:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/keys/key_AM7eAiR0BiaXTam951XmC9kK \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/keys/key_AM7eAiR0BiaXTam951XmC9kK \
   --request DELETE \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 ```
@@ -282,7 +282,7 @@ runtime, patch the consumer:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123 \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123 \
   --request PATCH \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -305,12 +305,12 @@ append `?tag.orgId=org_123` to every call:
 ```shell
 # List only consumers belonging to org_123
 curl \
-  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers?tag.orgId=org_123&include-api-keys=true&key-format=masked" \
+  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers?tag.orgId=org_123&include-api-keys=true&key-format=masked" \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 
 # Delete a consumer - fails if the consumer doesn't have tag orgId=org_123
 curl \
-  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123?tag.orgId=org_123" \
+  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123?tag.orgId=org_123" \
   --request DELETE \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 ```
@@ -333,7 +333,7 @@ app.use(express.json());
 
 const ZUPLO_BASE = "https://dev.zuplo.com/v1/accounts";
 const ZUPLO_ACCOUNT = process.env.ZUPLO_ACCOUNT;
-const ZUPLO_BUCKET = process.env.ZUPLO_BUCKET;
+const ZUPLO_BUCKET_ID = process.env.ZUPLO_BUCKET_ID;
 const ZUPLO_API_KEY = process.env.ZUPLO_API_KEY;
 
 // TODO: Replace with your real auth middleware
@@ -351,7 +351,7 @@ app.get("/api/keys", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/keys?key-format=masked`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/keys?key-format=masked`,
     {
       headers: { Authorization: `Bearer ${ZUPLO_API_KEY}` },
     },
@@ -366,7 +366,7 @@ app.post("/api/keys", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/keys`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/keys`,
     {
       method: "POST",
       headers: {
@@ -386,7 +386,7 @@ app.post("/api/keys/rotate", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/roll-key?tag.orgId=${orgId}`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/roll-key?tag.orgId=${orgId}`,
     {
       method: "POST",
       headers: {
@@ -406,7 +406,7 @@ app.delete("/api/keys/:keyId", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/keys/${req.params.keyId}?tag.orgId=${orgId}`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/keys/${req.params.keyId}?tag.orgId=${orgId}`,
     {
       method: "DELETE",
       headers: { Authorization: `Bearer ${ZUPLO_API_KEY}` },

package/docs/articles/audit-logs.mdx

@@ -121,12 +121,13 @@ The events view lets you:
 Everything in the portal is backed by the Zuplo API, so you can query audit logs
 programmatically — for scripting, custom dashboards, or exporting to other
 systems. Authenticate with a [Zuplo API key](./accounts/zuplo-api-keys.mdx) and
-query events by bucket name. Your bucket name is shown on the **API Keys →
-Consumers** page in the portal, as the copyable pill under the **API Key
-Service** heading (it's the same bucket used by the API Key Service).
+query events by bucket ID. Copy the bucket ID from the copyable **Bucket ID**
+pill under the **API Key Service** heading on the
+[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
+page in the portal (it's the same bucket used by the API Key Service).
 
 ```bash
-curl "https://dev.zuplo.com/v1/audit-logs/$BUCKET_NAME/events?type=com.zuplo.api.request&startDate=2026-07-01T00:00:00Z&endDate=2026-07-07T00:00:00Z" \
+curl "https://dev.zuplo.com/v1/audit-logs/$BUCKET_ID/events?type=com.zuplo.api.request&startDate=2026-07-01T00:00:00Z&endDate=2026-07-07T00:00:00Z" \
   -H "Authorization: Bearer $ZUPLO_API_KEY"
 ```
 
@@ -163,10 +164,10 @@ Two endpoints are available:
 - **Aggregated stats** — `GET /v1/audit-logs/{bucketId}/stats` returns top-N
   event counts grouped by event type or actor.
 
-The `bucketId` path parameter accepts either the bucket ID or the bucket name.
-Each query is limited to a 30-day window between `startDate` and `endDate`. See
-the [Audit Logs API reference](../api/audit-logs) for all parameters and
-response schemas.
+The `bucketId` path parameter takes the bucket ID; these endpoints don't accept
+a bucket name. Each query is limited to a 30-day window between `startDate` and
+`endDate`. See the [Audit Logs API reference](../api/audit-logs) for all
+parameters and response schemas.
 
 ## Exporting audit logs to a SIEM
 
@@ -182,14 +183,14 @@ const BASE_URL = "https://dev.zuplo.com/v1/audit-logs";
 // Run on a schedule (e.g. every 5 minutes). `startDate` is the checkpoint
 // saved by the previous run; `endDate` is the current time.
 async function exportAuditLogs(
-  bucketName: string,
+  bucketId: string,
   startDate: string,
   endDate: string,
 ) {
   let offset = 0;
   let hasMore = true;
   while (hasMore) {
-    const url = new URL(`${BASE_URL}/${bucketName}/events`);
+    const url = new URL(`${BASE_URL}/${bucketId}/events`);
     url.searchParams.set("startDate", startDate);
     url.searchParams.set("endDate", endDate);
     url.searchParams.set("limit", "100");

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

@@ -37,7 +37,7 @@ are set in your terminal:
 
 ```bash
 # Your Bucket ID (could be working-copy, preview, or production)
-# (Copy it from Bucket Details on Services > API Keys > Consumers — https://portal.zuplo.com/+/account/project/services)
+# (Copy it from the Bucket ID pill on Services > API Keys > Consumers — https://portal.zuplo.com/+/account/project/services)
 export BUCKET_ID=your-bucket-id
 # Your Zuplo API Key (Found in Account Settings > Zuplo API Keys —
 # https://portal.zuplo.com/+/account/settings/api-keys)

package/docs/articles/monetization/going-to-production.mdx

@@ -459,7 +459,7 @@ To help the team resolve your issue quickly, include:
 | ------------------ | ------------------------------------------------------ |
 | Account slug       | Your Zuplo account identifier                          |
 | Project slug       | The project with monetization enabled                  |
-| Bucket ID          | Bucket Details on Services → API Keys → Consumers      |
+| Bucket ID          | The Bucket ID pill on Services → API Keys → Consumers  |
 | Stripe account ID  | Stripe Dashboard → Settings, starts with `acct_`       |
 | Plan keys          | The plan keys involved in the issue                    |
 | Subscription ID    | If the issue is subscription-specific                  |

package/docs/concepts/ai-gateway.mdx

@@ -21,9 +21,10 @@ Three building blocks organize an AI Gateway:
   can route to. Administrators configure providers once, including any
   [custom OpenAI-compatible providers](../ai-gateway/custom-providers.mdx), and
   consumers never see the underlying credentials.
-- **[Teams](../ai-gateway/teams.mdx)** group users and carry budget limits that
-  cascade down the hierarchy: gateway-wide limits, then team limits, then
-  per-app limits. See [Usage Limits](../ai-gateway/usage-limits.mdx).
+- **[Teams](../ai-gateway/teams.mdx)** group users and carry budget limits. Each
+  team totals usage across its sub-teams and apps. A request must remain within
+  the gateway, ancestor team, and app limits. See
+  [Usage Limits](../ai-gateway/usage-limits.mdx).
 - **[Apps](../ai-gateway/apps.mdx)** are the pieces of software that call the
   gateway — a support chatbot is one app, an internal coding agent is another.
   Each app gets its own gateway URL, its own Zuplo-managed API key, and its own

package/docs/concepts/api-keys.md

@@ -187,7 +187,7 @@ Each project has separate buckets for production, preview, and working copy
 environments. This means API keys created in production don't work in preview,
 and vice versa.
 
-For testing, you can specify a custom bucket name on the
+For testing, you can specify a custom bucket ID on the
 [API Key Authentication](../policies/api-key-inbound.mdx) policy to share keys
 across environments. Enterprise customers can share buckets across projects or
 accounts.

package/docs/dedicated/akamai/ai-powered-applications.mdx

@@ -165,14 +165,17 @@ When the firewall detects a threat, it can take one of three actions:
 
 ## Cost and Usage Controls
 
-The Zuplo AI Gateway provides hierarchical budget controls to manage AI
-spending:
-
-- **Organization limits** - Maximum daily and monthly spending across all AI
-  usage
-- **Team budgets** - Allocated budgets for departments or customer segments
-- **Application limits** - Per-application or per-use-case cost controls
-- **Rate limiting** - Request throttling to prevent abuse
+The Zuplo AI Gateway provides budget controls at every level of the hierarchy to
+manage AI spending:
+
+- **Gateway budgets** - Hourly, daily, weekly, or monthly limits across all AI
+  Gateway usage.
+- **Team budgets** - Shared or per-expression limits across a team, its
+  sub-teams, and their apps.
+- **App budgets** - Shared or per-expression limits for one app.
+- **Rate limiting** - Request throttling to prevent abuse.
+
+For more information, see [Usage Limits](../../ai-gateway/usage-limits.mdx).
 
 ## Security Model
 

package/docs/dev-portal/dev-portal-create-consumer-on-auth.mdx

@@ -56,14 +56,19 @@ secret `API_KEY` and set the value.
 
 :::info
 
-In the code below set the variable `BUCKET_NAME` to the bucket being used by
-your Zuplo Gateway. If you don't know the name of your bucket, you can
+In the code below set the variable `API_KEY_BUCKET_ID` to the ID of the bucket
+being used by your Zuplo Gateway. Copy it from the **Bucket ID** pill on your
+project's
+[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
+page, or
 [list your buckets using the Developer API](https://dev.zuplo.com/docs/routes#apikeybucketsservice_list).
+For more information, see
+[Bucket identifiers](../articles/api-key-buckets.mdx#bucket-identifiers).
 
 :::
 
 Next, add the following code to your custom action. Be sure to replace the
-placeholder values with your actual account and bucket names. Click the
+placeholder values with your actual account name and bucket ID. Click the
 **Deploy** button when you are finished.
 
 ```ts
@@ -71,7 +76,7 @@ const { fetch } = require("undici");
 const { randomUUID } = require("crypto");
 
 const ZUPLO_ACCOUNT = "my-zuplo-account";
-const API_KEY_BUCKET = "my-bucket";
+const API_KEY_BUCKET_ID = "bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL";
 
 /**
  * Handler that will be called during the execution of a PostLogin flow.
@@ -100,7 +105,7 @@ exports.onExecutePostLogin = async (event, api) => {
   try {
     // Create the consumer
     const response = await fetch(
-      `https://dev.zuplo.com/v1/accounts/${ZUPLO_ACCOUNT}/key-buckets/${API_KEY_BUCKET}/consumers?with-api-key=true`,
+      `https://dev.zuplo.com/v1/accounts/${ZUPLO_ACCOUNT}/key-buckets/${API_KEY_BUCKET_ID}/consumers?with-api-key=true`,
       {
         method: "POST",
         body: JSON.stringify(body),

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -319,7 +319,7 @@ selected from the request. Each expression rule requires one or more meter rows:
 | `meter`    | `cost`, `requests`, `tokens`                         |
 | `period`   | `hourly`, `daily`, `weekly`, `monthly`               |
 | `action`   | `warn` records a warning; `block` returns HTTP `429` |
-| `value`    | A finite number greater than or equal to zero        |
+| `value`    | A finite number greater than zero                    |
 
 A rule cannot repeat the same meter, period, and action. When a meter and period
 have both actions, the `warn` value must be less than the `block` value. The

package/docs/policies/ai-gateway-metering-v2-inbound/schema.json

@@ -103,7 +103,7 @@
                         },
                         "value": {
                           "type": "number",
-                          "minimum": 0
+                          "exclusiveMinimum": 0
                         },
                         "action": {
                           "type": "string",

package/docs/policies/semantic-cache-inbound/schema.json

@@ -61,8 +61,12 @@
             },
             "cacheByPropertyPath": {
               "type": "string",
-              "description": "The path to the property in the request body (JSON) to use as cache key. For example '.userId' would read the 'userId' property from the request body. Only works with cacheBy=propertyPath.",
-              "examples": [".userId", ".data.customerId"]
+              "description": "A light path selector into the JSON request body to use as the cache key. Start with `.` for dot notation or `[` for a quoted key containing dots or slashes, for example `.userId`, `.data.customerId`, or `[\"https://example.com/cache-key\"]`. Only works with cacheBy=propertyPath.",
+              "examples": [
+                ".userId",
+                ".data.customerId",
+                "[\"https://example.com/cache-key\"]"
+              ]
             },
             "cacheByFunction": {
               "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.4",
+  "version": "7.6.5",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.4",
-    "@zuplo/core": "7.6.4",
-    "@zuplo/runtime": "7.6.4",
-    "@zuplo/test": "7.6.4"
+    "@zuplo/cli": "7.6.5",
+    "@zuplo/core": "7.6.5",
+    "@zuplo/runtime": "7.6.5",
+    "@zuplo/test": "7.6.5"
   }
 }