Document shared organization credit balance

assistant/configure.mdx

@@ -29,7 +29,7 @@
 <Tip>
 If you prefer to route support questions to your existing support channels instead, disable the **Contact form** in the Response handling section.
 
 When you disable the contact form, the assistant directs users to your support email address in plain text instead of showing the in-chat form. Sales questions still use the in-chat form when a sales email is configured.
 </Tip>
 
 ## Search domains
@@ -97,13 +97,13 @@
 
 ### Allow overages
 
-Mintlify disables overages by default. When overages are off, the assistant becomes unavailable once you reach your credit allowance and stays unavailable until your allowance resets.
+Credits are shared across your organization, but overages are configured per deployment. Mintlify disables overages by default. When overages are off for a deployment, the assistant on that deployment becomes unavailable once your organization's shared credit balance is spent, and stays unavailable until the balance resets.
 
-To allow overages, enable them in the **Spending controls** section of the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. If you enable overages, each credit beyond your allowance incurs an overage charge.
+To allow overages, enable them in the **Spending controls** section of the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. If you enable overages, each credit spent beyond the shared balance incurs an overage charge.
 
 ### Set usage alerts
 
-In the **Spending controls** section of your dashboard, set usage alerts to receive an email when you reach a certain percentage of your credit allowance.
+In the **Spending controls** section of your dashboard, set usage alerts to receive an email when your organization reaches a certain percentage of its shared credit balance.
 
 ### Higher credit volumes
 

assistant/index.mdx

@@ -6,7 +6,7 @@ boost: 3
 ---
 
 <Info>
-  The assistant is available on the [Pro plan and above](https://mintlify.com/pricing?ref=assistant). Every Pro plan includes 10,000 credits per month shared across the assistant, agent, and automations. See [Manage billing](/assistant/configure#manage-billing) for more information about credit tiers and options.
+  The assistant is available on the [Pro plan and above](https://mintlify.com/pricing?ref=assistant). Every Pro plan contributes 10,000 credits per month to your organization's shared credit balance, used across the assistant, agent, and automations on every deployment. See [Manage billing](/assistant/configure#manage-billing) for more information about credit tiers and options.
 </Info>
 
 ## About the assistant

credits.mdx

@@ -14,14 +14,33 @@
 
 ## Plan availability
 
-Credits are available on the **Pro and Enterprise plans**. Every Pro plan includes 10,000 credits per month, and you can purchase additional credits from the [Usage](https://app.mintlify.com/settings/organization/usage) page whenever you need more.
+Credits are available on the **Pro and Enterprise plans**. Every Pro plan contributes 10,000 credits per month to your organization's shared credit balance, and you can purchase additional credits from the [Usage](https://app.mintlify.com/settings/organization/usage) page whenever you need more.
 
 The free Starter plan does not include AI features. You cannot purchase credits on the Starter plan. To use the assistant, agent, or automations, upgrade to Pro or Enterprise.
 
 <Note>
   Customers on legacy credit plans keep their existing credit packs and pricing. The tiers below apply to the Pro plan.
 </Note>
 
+## Shared organization balance
+
+Credits are held at the organization level. Every deployment in your organization draws from a single shared balance made up of:
+
+- **Included credits** — Each paid deployment's plan credits, combined into one pool. For example, two Pro deployments at 10,000 credits each give the organization 20,000 credits per month.
+- **Add-on credits** — Extra credits purchased once for the whole organization rather than per deployment. Any deployment can spend them.
+- **Rollover credits** — Unused credits carried into the next period, also shared across the organization.
+
+What stays per deployment:
+
+- The **plan** itself.
+- The **overage setting** that controls whether that deployment may keep running once the shared balance is spent. When the pool runs dry, each deployment's own overage setting decides what happens to it.
+
+Elsewhere in the product:
+
+- The [Usage](https://app.mintlify.com/settings/organization/usage) page shows the organization-wide balance, with per-deployment usage broken out below it.
+- Buying add-on credits is one purchase for the organization instead of one per deployment.
+- Usage alert emails are sent for the organization as a whole rather than for a single deployment.
+
 ## Pricing tiers
 
 | Monthly credits | Monthly cost |
@@ -33,13 +52,13 @@
 
 If you need more than 100,000 credits per month, [contact sales](https://www.mintlify.com/contact/sales) to discuss a custom plan.
 
-**Overages** cost an additional $0.01 per credit rather than triggering an automatic tier upgrade. You can set usage alerts to receive an email when you reach a certain percentage of your tier limit. Allowing overages can be cheaper than moving up a tier depending on your usage patterns.
+**Overages** cost an additional $0.01 per credit rather than triggering an automatic tier upgrade. You can set usage alerts to receive an email when your organization reaches a certain percentage of its credit balance. Allowing overages can be cheaper than moving up a tier depending on your usage patterns.
 
 <Note>
-  Overages default to off. You must enable them on the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard.
+  Overages default to off and are configured per deployment. Enable them on the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. When the organization's shared balance is spent, each deployment's own overage setting decides whether that deployment keeps running.
 </Note>
 
-**Rollovers** carry forward up to 50% of unused credits to the next month, so the maximum credits available in any month is 1.5 times your monthly limit. Rollovers reset if you change tiers.
+**Rollovers** carry forward up to 50% of the organization's unused credits to the next month, so the maximum credits available in any month is 1.5 times your monthly limit. Rollovers reset if you change tiers.
 
 Higher tiers offer a lower effective cost per credit. If your usage consistently reaches the top of your current tier, upgrading is more economical than paying ongoing overage charges.