docs: reference billing-controls from the balances skill instead of merging

billing-controls.md stays the owner of the control definitions and
concepts.mdx returns to base; the balances skill inlines the owner after
its balance-specific commentary. The strictest-wins scope claim still
gives way to the owner's entity-override rule (flagged for review).

Author: charlietlamb

packages/agent-docs/content/skills/balances/balances.mdx

@@ -6,3 +6,5 @@ description: How a balance behaves at zero — what makes an included allowance
 # Balances
 
 <part file="../concepts/references/balances.md" inline="true" />
+
+<part file="../concepts/references/billing-controls.md" inline="true" />

packages/agent-docs/content/skills/concepts/concepts.mdx

@@ -76,4 +76,4 @@ Load the matching definition when reasoning about that object.
 
 <part file="references/customer-entity.md" when="distinguishing a customer from an entity (seats, sub-accounts) and their runtime billing state" />
 
-<part file="references/balances.md" when="reasoning about balances, caps, overage, or billing controls — runtime caps, alerts, and top-ups" />
+<part file="references/billing-controls.md" when="reasoning about billing controls — runtime caps, alerts, overage, and top-ups" />

packages/agent-docs/content/skills/concepts/references/balances.md

@@ -7,22 +7,13 @@
 - If neither is set, `included` IS the cap: usage stops at 0 and `check` returns `allowed: false`. Nothing extra is needed to enforce it.
 - So never add a `spend_limit` to "cap" a feature that has no overage price and no `overage_allowed` — it is already capped, and the limit does nothing.
 
-### Billing controls
-
-Billing controls are runtime policy on a customer or entity: they never define what a plan grants, only how usage is allowed, capped, alerted, or topped up. They are often exposed as customer-facing settings, except `overage_allowed`, which is usually product/admin controlled.
-
-- Only `overage_allowed` changes whether usage may pass 0. The rest just bound usage that is already permitted.
-- `spend_limits`: caps overage only, in feature units (not dollars). With no overage there is nothing to bound, so it does nothing.
-- `usage_limits`: a separate gate on TOTAL usage per time window, counted independently of the balance. This one bites whether or not overage exists, and can sit below the included amount. Useful when a plan grants multiple balances (5/day and 5/month) but the customer also needs a separate 100/month cap, or when shared credits need a per-action cap (10 `action_1` calls/day).
-- `usage_alerts`: notify when usage crosses a threshold; alerts never block usage. Never describe alerts as blocking, or spend limits as dollar limits unless the feature's units are dollars.
-- `auto_topups`: automatically buy prepaid units when the balance drops below a threshold. Verify the feature has a one-off prepaid purchase path first.
-- Entity-level controls override customer-level controls for that entity. Auto top-ups are customer-level only.
-- Inspect current customer/entity state before changing billing controls.
-
-Docs: [billing controls](https://docs.useautumn.com/documentation/customers/billing-controls), [auto top-ups](https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups), [spend limits and usage alerts](https://docs.useautumn.com/documentation/modelling-pricing/spend-limits).
-
 ### Tracking past zero
 
 - On `track`, `overage_behavior` decides what happens to a deduction that does not fit.
 - `cap` (default): deducts only what fits and stops at 0.
 - `overflow`: deducts the whole value and lets the balance go negative. `usage_limits` do not clamp it; `spend_limits` still apply.
+
+### How controls interact with balances
+
+- Only `overage_allowed` changes whether usage may pass 0. The rest just bound usage that is already permitted — with no overage, a `spend_limit` has nothing to bound and does nothing.
+- `usage_limits` are counted independently of the balance: they bite whether or not overage exists, and can sit below the included amount.

packages/agent-docs/content/skills/concepts/references/billing-controls.md

@@ -0,0 +1,43 @@
+### Billing Controls
+
+- Billing controls are runtime policy on a customer or entity.
+- They do not define what a plan grants; they change how usage is allowed, capped, alerted, or topped up.
+- They are often exposed as customer-facing settings, except `overage_allowed` which is usually product/admin controlled.
+
+</intro>
+
+<control-types>
+
+- `overage_allowed`: whether usage can continue after granted balance is exhausted.
+- `spend_limits`: cap overage in feature units, not dollars.
+- `usage_limits`: hard usage caps over a time window.
+  - Useful when a plan grants multiple balances, e.g. 5/day and 5/month, but the customer also needs a separate 100/month cap.
+  - Useful for credit systems when credits are shared, but one mapped action needs its own cap, e.g. 10 `action_1` calls/day.
+- `usage_alerts`: notify when usage crosses a threshold; alerts do not block usage.
+- `auto_topups`: automatically buy prepaid quantity when balance drops below a threshold.
+
+</control-types>
+
+<scope>
+
+- Customer-level controls apply to the customer.
+- Entity-level controls can override customer-level controls for that entity.
+- Auto top-ups are customer-level only.
+
+</scope>
+
+<agent-rules>
+
+- Inspect current customer/entity state before changing billing controls.
+- For auto top-ups, verify the feature has a one-off prepaid purchase path.
+- Do not describe alerts as blocking usage or spend limits as dollar limits unless the feature units are dollars.
+
+</agent-rules>
+
+<useful-docs>
+
+- Billing controls: https://docs.useautumn.com/documentation/customers/billing-controls
+- Auto top-ups: https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups
+- Spend limits and usage alerts: https://docs.useautumn.com/documentation/modelling-pricing/spend-limits
+
+</useful-docs>

packages/agent-docs/generated/mcp/concepts.md

@@ -588,31 +588,46 @@ Updating or ending a trial
 
 </useful-docs>
 
-## Balances, caps and overage
+### Billing Controls
 
-- A balance counts down to 0. Going below 0 is overage.
-- Two things let usage go past 0, and nothing else does:
-  - a usage-based `price` on the plan item — they go over and get billed for it.
-  - the `overage_allowed` billing control.
-- If neither is set, `included` IS the cap: usage stops at 0 and `check` returns `allowed: false`. Nothing extra is needed to enforce it.
-- So never add a `spend_limit` to "cap" a feature that has no overage price and no `overage_allowed` — it is already capped, and the limit does nothing.
+- Billing controls are runtime policy on a customer or entity.
+- They do not define what a plan grants; they change how usage is allowed, capped, alerted, or topped up.
+- They are often exposed as customer-facing settings, except `overage_allowed` which is usually product/admin controlled.
 
-### Billing controls
+</intro>
+
+<control-types>
+
+- `overage_allowed`: whether usage can continue after granted balance is exhausted.
+- `spend_limits`: cap overage in feature units, not dollars.
+- `usage_limits`: hard usage caps over a time window.
+  - Useful when a plan grants multiple balances, e.g. 5/day and 5/month, but the customer also needs a separate 100/month cap.
+  - Useful for credit systems when credits are shared, but one mapped action needs its own cap, e.g. 10 `action_1` calls/day.
+- `usage_alerts`: notify when usage crosses a threshold; alerts do not block usage.
+- `auto_topups`: automatically buy prepaid quantity when balance drops below a threshold.
+
+</control-types>
+
+<scope>
 
-Billing controls are runtime policy on a customer or entity: they never define what a plan grants, only how usage is allowed, capped, alerted, or topped up. They are often exposed as customer-facing settings, except `overage_allowed`, which is usually product/admin controlled.
+- Customer-level controls apply to the customer.
+- Entity-level controls can override customer-level controls for that entity.
+- Auto top-ups are customer-level only.
+
+</scope>
+
+<agent-rules>
 
-- Only `overage_allowed` changes whether usage may pass 0. The rest just bound usage that is already permitted.
-- `spend_limits`: caps overage only, in feature units (not dollars). With no overage there is nothing to bound, so it does nothing.
-- `usage_limits`: a separate gate on TOTAL usage per time window, counted independently of the balance. This one bites whether or not overage exists, and can sit below the included amount. Useful when a plan grants multiple balances (5/day and 5/month) but the customer also needs a separate 100/month cap, or when shared credits need a per-action cap (10 `action_1` calls/day).
-- `usage_alerts`: notify when usage crosses a threshold; alerts never block usage. Never describe alerts as blocking, or spend limits as dollar limits unless the feature's units are dollars.
-- `auto_topups`: automatically buy prepaid units when the balance drops below a threshold. Verify the feature has a one-off prepaid purchase path first.
-- Entity-level controls override customer-level controls for that entity. Auto top-ups are customer-level only.
 - Inspect current customer/entity state before changing billing controls.
+- For auto top-ups, verify the feature has a one-off prepaid purchase path.
+- Do not describe alerts as blocking usage or spend limits as dollar limits unless the feature units are dollars.
 
-Docs: [billing controls](https://docs.useautumn.com/documentation/customers/billing-controls), [auto top-ups](https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups), [spend limits and usage alerts](https://docs.useautumn.com/documentation/modelling-pricing/spend-limits).
+</agent-rules>
 
-### Tracking past zero
+<useful-docs>
 
-- On `track`, `overage_behavior` decides what happens to a deduction that does not fit.
-- `cap` (default): deducts only what fits and stops at 0.
-- `overflow`: deducts the whole value and lets the balance go negative. `usage_limits` do not clamp it; `spend_limits` still apply.
+- Billing controls: https://docs.useautumn.com/documentation/customers/billing-controls
+- Auto top-ups: https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups
+- Spend limits and usage alerts: https://docs.useautumn.com/documentation/modelling-pricing/spend-limits
+
+</useful-docs>

packages/agent-docs/generated/skills/autumn-concepts/SKILL.md

@@ -76,4 +76,4 @@ For reasoning about free trials and when billing begins, read `references/trials
 
 For distinguishing a customer from an entity (seats, sub-accounts) and their runtime billing state, read `references/customer-entity.md`.
 
-For reasoning about balances, caps, overage, or billing controls — runtime caps, alerts, and top-ups, read `references/balances.md`.
+For reasoning about billing controls — runtime caps, alerts, overage, and top-ups, read `references/billing-controls.md`.

packages/agent-docs/generated/skills/autumn-concepts/references/billing-controls.md

@@ -0,0 +1,43 @@
+### Billing Controls
+
+- Billing controls are runtime policy on a customer or entity.
+- They do not define what a plan grants; they change how usage is allowed, capped, alerted, or topped up.
+- They are often exposed as customer-facing settings, except `overage_allowed` which is usually product/admin controlled.
+
+</intro>
+
+<control-types>
+
+- `overage_allowed`: whether usage can continue after granted balance is exhausted.
+- `spend_limits`: cap overage in feature units, not dollars.
+- `usage_limits`: hard usage caps over a time window.
+  - Useful when a plan grants multiple balances, e.g. 5/day and 5/month, but the customer also needs a separate 100/month cap.
+  - Useful for credit systems when credits are shared, but one mapped action needs its own cap, e.g. 10 `action_1` calls/day.
+- `usage_alerts`: notify when usage crosses a threshold; alerts do not block usage.
+- `auto_topups`: automatically buy prepaid quantity when balance drops below a threshold.
+
+</control-types>
+
+<scope>
+
+- Customer-level controls apply to the customer.
+- Entity-level controls can override customer-level controls for that entity.
+- Auto top-ups are customer-level only.
+
+</scope>
+
+<agent-rules>
+
+- Inspect current customer/entity state before changing billing controls.
+- For auto top-ups, verify the feature has a one-off prepaid purchase path.
+- Do not describe alerts as blocking usage or spend limits as dollar limits unless the feature units are dollars.
+
+</agent-rules>
+
+<useful-docs>
+
+- Billing controls: https://docs.useautumn.com/documentation/customers/billing-controls
+- Auto top-ups: https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups
+- Spend limits and usage alerts: https://docs.useautumn.com/documentation/modelling-pricing/spend-limits
+
+</useful-docs>

packages/agent-docs/generated/skills/balances/SKILL.md

@@ -14,22 +14,57 @@ description: How a balance behaves at zero — what makes an included allowance
 - If neither is set, `included` IS the cap: usage stops at 0 and `check` returns `allowed: false`. Nothing extra is needed to enforce it.
 - So never add a `spend_limit` to "cap" a feature that has no overage price and no `overage_allowed` — it is already capped, and the limit does nothing.
 
-### Billing controls
+### Tracking past zero
+
+- On `track`, `overage_behavior` decides what happens to a deduction that does not fit.
+- `cap` (default): deducts only what fits and stops at 0.
+- `overflow`: deducts the whole value and lets the balance go negative. `usage_limits` do not clamp it; `spend_limits` still apply.
+
+### How controls interact with balances
+
+- Only `overage_allowed` changes whether usage may pass 0. The rest just bound usage that is already permitted — with no overage, a `spend_limit` has nothing to bound and does nothing.
+- `usage_limits` are counted independently of the balance: they bite whether or not overage exists, and can sit below the included amount.
+
+### Billing Controls
+
+- Billing controls are runtime policy on a customer or entity.
+- They do not define what a plan grants; they change how usage is allowed, capped, alerted, or topped up.
+- They are often exposed as customer-facing settings, except `overage_allowed` which is usually product/admin controlled.
+
+</intro>
+
+<control-types>
 
-Billing controls are runtime policy on a customer or entity: they never define what a plan grants, only how usage is allowed, capped, alerted, or topped up. They are often exposed as customer-facing settings, except `overage_allowed`, which is usually product/admin controlled.
+- `overage_allowed`: whether usage can continue after granted balance is exhausted.
+- `spend_limits`: cap overage in feature units, not dollars.
+- `usage_limits`: hard usage caps over a time window.
+  - Useful when a plan grants multiple balances, e.g. 5/day and 5/month, but the customer also needs a separate 100/month cap.
+  - Useful for credit systems when credits are shared, but one mapped action needs its own cap, e.g. 10 `action_1` calls/day.
+- `usage_alerts`: notify when usage crosses a threshold; alerts do not block usage.
+- `auto_topups`: automatically buy prepaid quantity when balance drops below a threshold.
+
+</control-types>
+
+<scope>
+
+- Customer-level controls apply to the customer.
+- Entity-level controls can override customer-level controls for that entity.
+- Auto top-ups are customer-level only.
+
+</scope>
+
+<agent-rules>
 
-- Only `overage_allowed` changes whether usage may pass 0. The rest just bound usage that is already permitted.
-- `spend_limits`: caps overage only, in feature units (not dollars). With no overage there is nothing to bound, so it does nothing.
-- `usage_limits`: a separate gate on TOTAL usage per time window, counted independently of the balance. This one bites whether or not overage exists, and can sit below the included amount. Useful when a plan grants multiple balances (5/day and 5/month) but the customer also needs a separate 100/month cap, or when shared credits need a per-action cap (10 `action_1` calls/day).
-- `usage_alerts`: notify when usage crosses a threshold; alerts never block usage. Never describe alerts as blocking, or spend limits as dollar limits unless the feature's units are dollars.
-- `auto_topups`: automatically buy prepaid units when the balance drops below a threshold. Verify the feature has a one-off prepaid purchase path first.
-- Entity-level controls override customer-level controls for that entity. Auto top-ups are customer-level only.
 - Inspect current customer/entity state before changing billing controls.
+- For auto top-ups, verify the feature has a one-off prepaid purchase path.
+- Do not describe alerts as blocking usage or spend limits as dollar limits unless the feature units are dollars.
 
-Docs: [billing controls](https://docs.useautumn.com/documentation/customers/billing-controls), [auto top-ups](https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups), [spend limits and usage alerts](https://docs.useautumn.com/documentation/modelling-pricing/spend-limits).
+</agent-rules>
 
-### Tracking past zero
+<useful-docs>
 
-- On `track`, `overage_behavior` decides what happens to a deduction that does not fit.
-- `cap` (default): deducts only what fits and stops at 0.
-- `overflow`: deducts the whole value and lets the balance go negative. `usage_limits` do not clamp it; `spend_limits` still apply.
+- Billing controls: https://docs.useautumn.com/documentation/customers/billing-controls
+- Auto top-ups: https://docs.useautumn.com/documentation/modelling-pricing/auto-top-ups
+- Spend limits and usage alerts: https://docs.useautumn.com/documentation/modelling-pricing/spend-limits
+
+</useful-docs>