docs: document quarterly budgets and fiscal quarter configuration

[akshaydeo]

Summary

Adds 1Q (quarterly) as a valid reset_duration for budgets and introduces a companion reset_config object that lets operators configure a custom fiscal quarter start month. This allows budgets to reset on non-calendar-year fiscal quarters (e.g. UK/India April, US federal October, Australia July).

Changes

• 1Q is added to the reset_duration enum on budget schemas across the OpenAPI spec, config JSON schema, and all documentation. Rate limit schemas intentionally retain the existing enum without 1Q, since quarterly token/request limits are not supported.
• A new optional reset_config object with a single quarter_start_month field (integer 1–12) is added to budget create/update requests and the Budget response schema. It is only valid when reset_duration is 1Q; the API rejects it on any other window.
• quarter_start_month sets the first month of Q1. Omitting it defaults to January (standard calendar quarters: Jan/Apr/Jul/Oct). Because quarter boundaries repeat every three months, only the value modulo 3 meaningfully shifts reset dates; the eight non-modulo-equivalent months (e.g. February) genuinely move boundaries.
• Calendar-aligned quarterly budgets reset on the 1st of the relevant month at 00:00 UTC. A non-calendar-aligned quarterly budget ignores the fiscal calendar and rolls on a 90-day window from creation.
• Changing quarter_start_month on a live calendar-aligned budget moves last_reset to the new fiscal boundary but preserves current accumulated spend.
• The ResetDuration schema in accessprofiles.yaml is split into BudgetResetDuration and RateLimitResetDuration to enforce the distinction between budget and rate-limit windows at the schema level.
• Documentation in budget-and-limits.mdx, governance.mdx, virtual-keys.mdx, and access-profiles.mdx is updated to cover the new duration, the reset_config field, fiscal quarter examples, and calendar-alignment behaviour for quarterly budgets.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

1. Create a budget with "reset_duration": "1Q" and no reset_config — verify it resets on standard calendar quarters (Jan/Apr/Jul/Oct).
2. Create a budget with "reset_duration": "1Q" and "reset_config": { "quarter_start_month": 4 } — verify reset dates shift to Apr/Jul/Oct/Jan.
3. Attempt to create a budget with "reset_duration": "1M" and a reset_config body — verify the API returns a validation error.
4. Attempt to create a rate limit with "reset_duration": "1Q" — verify the API rejects it.
5. On a live calendar-aligned quarterly budget, update quarter_start_month — verify last_reset moves to the new boundary and current usage is unchanged.
6. Validate the OpenAPI spec and config JSON schema parse without errors.

go test ./...

Breaking changes

• Yes
• No

Related issues

Security considerations

None. This change is additive and scoped to budget configuration; no authentication, secrets, or PII are affected.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[akshaydeo]

• governance: enabling calendar alignment preserves the open window #6013
• governance: extend reset_budget_usage to teams, customers, model limits and provider governance #6004
• governance: calendar alignment applies from the next period #6003
• adds reset budget honor flow #6002
• docs: document quarterly budgets and fiscal quarter configuration #6000 👈 (View in Graphite)
• ui: quarterly budget period with fiscal-quarter advanced settings #5999
• governance: quarterly budget windows with configurable fiscal start #5997
• quarterly budget #5996
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added quarterly (1Q) budget reset periods.
  • Added configurable fiscal quarter start months from January through December.
  • Added calendar-aligned quarterly budgets, including validation and usage-preserving updates when fiscal boundaries change.

• Documentation

  • Updated budget, virtual-key, access-profile, deployment, and API reference documentation with quarterly reset configuration and validation details.

Walkthrough

Quarterly budget resets now use 1Q and support an optional fiscal quarter start month. Schemas, handlers, tests, UI presentation, and documentation describe the new configuration and reset behavior.

Changes

Quarterly budget resets

Layer / File(s)	Summary
Budget and rate-limit schema contracts docs/openapi/schemas/management/accessprofiles.yaml, docs/openapi/schemas/management/governance.yaml	Budget schemas add 1Q and reset_config.quarter_start_month. Rate-limit schemas use a separate enum without quarterly resets.
Published schema and transport validation docs/openapi/openapi.json, transports/config.schema.json, transports/schema_test/config_schema_test.go	Published schemas expose quarterly configuration, month bounds, and calendar-alignment rules. Schema tests cover valid and invalid configurations.
Fiscal boundary update behavior transports/bifrost-http/handlers/governance.go, transports/bifrost-http/handlers/governance_test.go	Reset configuration updates preserve LastReset and usage. A changed fiscal boundary makes the budget due for later reset convergence.
Quarterly budget lifecycle tests plugins/governance/budgetcycle_test.go, tests/governance/test_utils.go, tests/governance/vkbudget_test.go	Tests cover initialization, reload preservation, fiscal-boundary changes, reset-worker convergence, and invalid configurations.
Documentation and quarter selector updates docs/features/governance/budget-and-limits.mdx, docs/deployment-guides/config-json/governance.mdx, docs/enterprise/access-profiles.mdx, docs/features/governance/virtual-keys.mdx, ui/components/ui/quarterStartSelect.tsx, ui/package.json	Documentation describes quarterly budgets and fiscal-quarter rules. The selector layout changes, and the UI package requires Node.js >=22.12.0.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant BudgetHandler
  participant BudgetState
  participant ResetWorker
  Client->>BudgetHandler: update quarterly reset_config
  BudgetHandler->>BudgetState: preserve LastReset and CurrentUsage
  BudgetHandler-->>Client: return updated configuration
  ResetWorker->>BudgetState: evaluate new fiscal WindowStart
  ResetWorker->>BudgetState: converge due budget boundary

Loading

Possibly related PRs

• maximhq/bifrost#6003: Both changes preserve budget usage and reset state while fiscal-quarter configuration changes.
• maximhq/bifrost#6004: Both changes update shared budget reconciliation logic while preserving reset state.

Suggested reviewers: pratham-mishra04, roroghost17

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies quarterly budgets and fiscal quarter configuration, but it emphasizes documentation more than the broader schema and behavior changes.
Description check	✅ Passed	The description covers the purpose, changes, affected areas, testing steps, breaking changes, security, and documentation updates; some checklist items remain unchecked.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch quarterly-budget-docs

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/deployment-guides/config-json/governance.mdx`:
- Line 128: Update the reset_config example in the governance configuration
table to use a concrete JSON number such as 4 for quarter_start_month, and
describe separately that valid values range from 1 through 12 while preserving
the existing January default.

In `@docs/features/governance/virtual-keys.mdx`:
- Line 41: Update the calendar-alignment description adjacent to the Reset
Duration list to include quarter alongside day, week, month, and year,
reflecting support for quarterly budgets.

In `@transports/config.schema.json`:
- Around line 6498-6509: Update the schema containing the reset_config property
to add an if/then conditional: when reset_config is present, require
reset_duration to equal "1Q". Preserve the existing reset_config validation and
reject configurations using it with other durations such as "1M" or "1h".

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6b9dd12c-20f7-41a2-b995-d9efd44f0c25

📥 Commits

Reviewing files that changed from the base of the PR and between 1f59867 and dcbff0d.

📒 Files selected for processing (8)

• docs/deployment-guides/config-json/governance.mdx
• docs/enterprise/access-profiles.mdx
• docs/features/governance/budget-and-limits.mdx
• docs/features/governance/virtual-keys.mdx
• docs/openapi/openapi.json
• docs/openapi/schemas/management/accessprofiles.yaml
• docs/openapi/schemas/management/governance.yaml
• transports/config.schema.json

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/governance/vkbudget_test.go`:
- Around line 216-227: Guard the type assertions in the budget response checks,
including the reads of resetConfig["quarter_start_month"] and
budget["last_reset"] near the shown block and the corresponding assertions
around the later budget validation block. Use comma-ok assertions, call t.Fatalf
with the observed value when a field is missing or has the wrong type, and only
convert or parse the values after validation.
- Around line 372-378: Update the cleanup branch around ExtractIDFromResponse in
the request-rejection test to read the virtual-key ID directly from resp’s
response body without invoking the fatal helper. Delete the returned entity when
an ID is present, then preserve the intended failure message for unexpectedly
accepted requests.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: cd495a93-fc3e-4b55-8855-e411fd7825fc

📥 Commits

Reviewing files that changed from the base of the PR and between 59065b6 and 40ad078.

📒 Files selected for processing (8)

• docs/features/governance/budget-and-limits.mdx
• docs/openapi/openapi.json
• docs/openapi/schemas/management/governance.yaml
• plugins/governance/budgetcycle_test.go
• tests/governance/test_utils.go
• tests/governance/vkbudget_test.go
• transports/bifrost-http/handlers/governance.go
• transports/bifrost-http/handlers/governance_test.go

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/openapi/schemas/management/governance.yaml
• docs/openapi/openapi.json
• docs/features/governance/budget-and-limits.mdx

[akshaydeo]

Merge activity

• Aug 10, 9:42 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 10, 9:49 PM UTC: Graphite rebased this pull request as part of a merge.
• Aug 10, 9:50 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
bifrost	🟢 Ready	View Preview	Aug 10, 2026, 9:50 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.