docs: add Budgets page under Cloud > Organizations

docs.json

@@ -465,7 +465,8 @@
               "openhands/usage/cloud/organizations/overview",
               "openhands/usage/cloud/organizations/managing-members",
               "openhands/usage/cloud/organizations/roles-permissions",
-              "openhands/usage/cloud/organizations/settings"
+              "openhands/usage/cloud/organizations/settings",
+              "openhands/usage/cloud/organizations/budgets"
             ]
           }
         ]

openhands/usage/cloud/organizations/budgets.mdx

@@ -0,0 +1,111 @@
+---
+title: Budgets
+description: Set spending limits for your organization and its members to keep AI spend under control.
+---
+
+## Overview
+
+Budgets let Admins and Owners cap AI spend at both the organization and individual user level. Use them to
+prevent runaway costs, give new members sensible default limits, and adjust limits on a per-user basis as
+needs change.
+
+<Note>
+  Managing budgets requires Admin or Owner permissions.
+</Note>
+
+## Budget Types
+
+OpenHands supports three complementary budget controls:
+
+- **Organization Budget** - A monthly spending cap for the entire organization, with alerts at defined thresholds.
+- **Default User Budget** - A budget automatically applied to new members when they join the organization.
+- **User Budget Overrides** - Per-user adjustments that raise or lower an individual's budget.
+
+## Organization Budget
+
+The organization budget defines the maximum amount your organization can spend on AI usage in a given month.
+When usage approaches or exceeds the cap, OpenHands notifies Admins and Owners.
+
+### Setting the Monthly Budget
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Organization**.
+3. Select the `Budgets` tab.
+4. Under `Organization Budget`, enter your monthly spending cap (e.g., `$10,000`).
+5. Click `Save Changes`.
+
+### Budget Alerts
+
+Once a monthly cap is set, OpenHands automatically tracks organization-wide spend and sends alerts to Admins
+and Owners when usage reaches the following thresholds:
+
+- **80%** of the monthly budget — early warning.
+- **90%** of the monthly budget — approaching the cap.
+- **100%** of the monthly budget — the cap has been reached.
+
+<Warning>
+  When the organization reaches 100% of its monthly budget, new conversations may be blocked until the next
+  billing cycle or until the budget is increased.
+</Warning>
+
+The budget resets automatically at the start of each calendar month.
+
+## Default User Budget
+
+The default user budget is applied to every new member when they are added to the organization. This ensures
+new users cannot spend beyond a defined amount before an Admin reviews their usage.
+
+### Setting the Default Budget
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Organization**.
+3. Select the `Budgets` tab.
+4. Under `Default User Budget`, enter the amount every new member should start with (e.g., `$500`).
+5. Click `Save Changes`.
+
+<Note>
+  Default user budgets are currently **lifetime budgets** — they represent the total amount a user can spend
+  from when they join until an Admin increases the limit. Monthly user budgets are on the roadmap.
+</Note>
+
+New members added to the organization after this setting is saved will automatically inherit the default
+budget. Existing members are not affected.
+
+## User Budget Overrides
+
+Admins and Owners can override an individual user's budget at any time — for example, to raise a developer's
+limit from `$500` to `$1,000` once they reach their default cap.
+
+### Adjusting a User's Budget
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Organization**.
+3. Select the `Members` tab.
+4. Locate the user in the member list and open their row.
+5. Update the `Budget` field to the new amount (increase or decrease).
+6. Click `Save Changes`.
+
+The new limit takes effect immediately. If the user was previously blocked by their old limit, they will be
+able to resume usage until the new limit is reached.
+
+## Monitoring Budget Usage
+
+Budget usage is visible from the **Organization** settings page:
+
+- The `Budgets` tab shows the current organization-wide spend against the monthly cap.
+- The `Members` tab shows each user's current spend against their individual budget.
+
+For programmatic access to per-member usage data, use:
+
+```
+GET /api/organizations/{org_id}/members/financial
+```
+
+This endpoint returns the current spend for each member, which you can compare against their configured
+budget.
+
+## Next Steps
+
+- [Organization Settings](/openhands/usage/cloud/organizations/settings) - Configure LLMs, credits, and Git organization claims.
+- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Invite users and manage roles.
+- [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand permission levels.