Codestin Search App

ssncferreira · 2026-07-29T13:15:25Z

Description

Adds documentation for AI Governance Cost Control, including how administrators configure budgets, how effective groups are resolved, how enforcement works, and where spend reporting is available.

Changes

Replace the placeholder cost control page with a full admin guide
Document deployment settings, group budgets, user overrides, and effective group resolution
Explain estimated spend, unpriced models, notifications, enforcement, and spend reporting
Add migration guidance for Coder Agents Cost Control
Add screenshots for group budgets and user overrides

Closes AIGOV-476.

Note

Initially generated by Coder Agents, modified and reviewed by @ssncferreira

Replace the AIGOV-476 placeholder with an admin guide covering budget concepts, deployment settings, group budgets, user overrides, spend estimation, enforcement, and monitoring.

linear-code · 2026-07-29T13:15:29Z

AIGOV-476

github-actions · 2026-07-29T13:15:43Z

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

docs/ai-coder/ai-gateway/cost-controls.md

…tion

…rols

ssncferreira · 2026-07-30T10:39:34Z

+| `coder_ai_gateway_cost_control_unpriced_token_usage_records_total` | Usage records with no known model price.        |
+| `coder_ai_gateway_cost_control_enforcement_duration_seconds`       | Duration of budget checks.                      |
+
+## Migrate from Coder Agents Cost Control


We should probably add a note on the release notes explaining that AI Governance is replacing Agents Cost Control with a link to this section. Wdyt? Any idea how the release notes are created?

Should be made known to the release manager as a callout. Usually you'd mark it as a breaking change.

I am the PM release manager and Marcin is the EM one, so we can help out with this. I will DM you the link to the current release notes to make sure they are accurate

coderagents · 2026-07-30T10:47:18Z

Documentation Check

Re-reviewed at 0fe47ac513. The price book link is now version-scoped, and the 500 failure-mode bullet I suggested earlier was deliberately removed; I'm withdrawing that suggestion below rather than re-raising it. The remaining findings are the two follow-up docs outside this PR, plus one open question.

Updates Needed

docs/ai-coder/ai-gateway/cost-controls.md - Version conflict on the migration date. Split into enforcement moving in v2.36 and the legacy Coder Agents Spend page remaining until v2.37, matching the in-product banner (site/src/pages/AISettingsPage/SpendPage/SpendPageView.tsx:240).
docs/ai-coder/ai-gateway/cost-controls.md - Notification recipients now read "deployment-wide Owners and User Admins, excluding the affected user", matching coderd/aibridgedserver/notifications.go:186-196.
docs/ai-coder/ai-gateway/cost-controls.md - Budget managed by another group correctly split between the same-organization caption and the cross-organization dash (GroupMemberBudgetCells.tsx:83-121,182-188).
docs/ai-coder/ai-gateway/cost-controls.md - CSV export authorization reworded to group-member read, matching enterprise/coderd/aibridge.go:1181-1184.
docs/ai-coder/ai-gateway/cost-controls.md - Migration bullets scoped to priced traffic (coderd/aibridgedserver/cost.go:70-79) and the chat error detail clarified (coderd/x/chatd/chaterror/message.go:36-42).
docs/ai-coder/ai-gateway/cost-controls.md - Avatar menu Unlimited variant documented (UserDropdownAISpend.tsx:19-22).
docs/images/aibridge/user-override-ai-budget.png - PII removed and filename convention fixed in 0fe47ac513. Verified visually: the dialog now shows member / [email protected] with an initials avatar, and the description reads "member's monthly limit is uncapped, charged to Cost Control group." The photographic avatar and the real username are gone, the file was renamed from user_override_ai_budget.png to hyphenated form, the markdown reference was updated, and no stale references to the old path remain.
docs/ai-coder/agents/platform-controls/usage-insights.md - Still open. checkUsageLimit is a no-op (coderd/x/chatd/chatd.go:1614-1618, #27535), so the "Usage limits" section documents behavior that no longer exists: the 409 Conflict at lines 38-39 is unreachable and the priority hierarchy at lines 26-33 governs nothing. The navigation path at lines 8 and 56 is also stale: it is Admin settings > AI > Spend (site/src/router.tsx:761,771). This PR's own WARNING tells readers those limits are no longer enforced, so leaving the page as-is puts the two docs in direct conflict.

⚠️ Unchanged through 0fe47ac513. Fine as a follow-up PR, but it should not lag this page going live.
docs/ai-coder/agents/platform-controls/index.md (lines 117-124) - Still open. The "Spend management" section still states administrators can cap LLM usage per user with per-user and per-group overrides. Point at AI Governance Cost Control for enforcement.

⚠️ Unchanged through 0fe47ac513.

Minor

docs/ai-coder/ai-gateway/cost-controls.md - Prometheus metrics duplication resolved by dropping the table and linking to the generated metrics reference.
~~docs/ai-coder/ai-gateway/cost-controls.md - Enforcement failure mode (500 on a failed budget check)~~ (bullet removed in 0fe47ac513). Withdrawing this suggestion: failure-mode content routes to the Support KB under the content guidelines, so dropping it is the better call. The "users without a budget have unlimited spend" sentence stays and still matches coderd/aibridged/http.go:148-162.
docs/images/aibridge/group-ai-budget.png - Recaptured at 800x306 (16 KB), scoped to the AI budget section. Verified free of personal data: only Monthly limit per member (1000) and $2,000/month, based on 2 members.
docs/ai-coder/ai-gateway/cost-controls.md - Price book link is now version-scoped to release/<VERSION> instead of main, which matches the version-scoping principle in the content guidelines. Verified the path resolves on a real release branch: coderd/aibridge/prices/data/prices.json exists on release/2.35.
docs/ai-coder/ai-gateway/cost-controls.md - Open question, not a blocker. Premium vs AI Governance add-on framing. Every cost control route is gated on codersdk.FeatureAIBridge (enterprise/coderd/coderd.go:507-536,620-690), for which IsAIGovernanceAddon() returns true, and which is entitled in both the premium and enterprise feature sets only because the IsAddonFeature() filter is commented out with // TODO: In future release, restore the f.IsAddonFeature() check. (codersdk/deployment.go:322-325,359-374). Confirm "included with a Premium license" is the intended messaging. docs/ai-coder/ai-gateway/standalone.md also still carries "state": ["ai governance add-on"] in the manifest while its siblings are premium.
docs/manifest.json - Title is now "AI Governance Cost Control" and the description reads "Configure AI Gateway budgets, enforcement, notifications, and spend reporting.", both matching the page H1. Manifest still parses as valid JSON. The (Premium) H1 suffix from the content guidelines is still absent, which is consistent with every sibling AI Gateway page, so treating that as intentional.

Automated review via Coder Agents

ssncferreira · 2026-07-30T11:43:02Z

+>
+> - Estimates exclude negotiated discounts, committed-use pricing, and
+>   provider-specific billing rules.
+> - Requests to models that are missing from the price table record token usage


This section was difficult to write because we are saying there is a problem (unknown prices aren't tracked), but we don't offer a viable solution. Open to suggestions

Out of scope of this PR but agreed it is a problem.

Yes, the solution itself is out of scope for this PR. The open to suggestions part was on improving the wording so it reads better.

johnstcn

Approving to unblock. Thanks for working on this Susana!

johnstcn · 2026-07-30T12:17:50Z

+| `coder_ai_gateway_cost_control_unpriced_token_usage_records_total` | Usage records with no known model price.        |
+| `coder_ai_gateway_cost_control_enforcement_duration_seconds`       | Duration of budget checks.                      |
+
+## Migrate from Coder Agents Cost Control


Should be made known to the release manager as a callout. Usually you'd mark it as a breaking change.

johnstcn · 2026-07-30T12:18:52Z

+>
+> - Estimates exclude negotiated discounts, committed-use pricing, and
+>   provider-specific billing rules.
+> - Requests to models that are missing from the price table record token usage


Out of scope of this PR but agreed it is a problem.

docs(docs/ai-coder/ai-gateway): document AI Gateway cost controls

0ecea78

Replace the AIGOV-476 placeholder with an admin guide covering budget concepts, deployment settings, group budgets, user overrides, spend estimation, enforcement, and monitoring.

github-actions Bot assigned ssncferreira Jul 29, 2026

ssncferreira added 4 commits July 29, 2026 14:01

docs(docs/ai-coder/ai-gateway): add Agents cost control migration sec…

d90394e

…tion

docs(docs/ai-coder/ai-gateway): document roles required for cost cont…

1047cba

…rols

docs: address self review

7fd3249

docs: address self review

f49934a

ssncferreira changed the title ~~docs(docs/ai-coder/ai-gateway): document AI Gateway cost controls~~ docs: document AI Gateway cost controls Jul 29, 2026

ssncferreira added 4 commits July 29, 2026 17:49

docs: address self review

4c1d3e8

docs: address self review

44e134c

docs: address self review

0e4feec

docs: address self review

c7aaf72

ssncferreira commented Jul 30, 2026

View reviewed changes

ssncferreira marked this pull request as ready for review July 30, 2026 10:40

ssncferreira requested a review from a team as a code owner July 30, 2026 10:40

Merge branch 'main' into docs/aigov-476-ai-gateway-cost-controls

8a2a7f5

ssncferreira requested review from ibetitsmike, jcjiang and johnstcn July 30, 2026 10:40

ssncferreira commented Jul 30, 2026

View reviewed changes

johnstcn approved these changes Jul 30, 2026

View reviewed changes

ssncferreira added 7 commits July 30, 2026 12:24

docs: address documentation check review

c8aa11f

docs: address documentation check review

c4f235a

docs: address documentation check review

8b9837b

docs: address review

3d9636d

docs: update images

63ae435

docs: address documentation check review

a0838dc

docs: address documentation check review

4ca701a

docs: address documentation check review

0fe47ac

ssncferreira enabled auto-merge (squash) July 30, 2026 14:58

ssncferreira merged commit 3f1973f into main Jul 30, 2026
30 checks passed

ssncferreira deleted the docs/aigov-476-ai-gateway-cost-controls branch July 30, 2026 15:04

github-actions Bot locked and limited conversation to collaborators Jul 30, 2026

ssncferreira added cherry-pick cherrypick/v2.36 labels Jul 30, 2026

Navigation Menu

Uh oh!

docs: document AI Gateway cost controls - #27643

docs: document AI Gateway cost controls#27643
ssncferreira merged 18 commits into
mainfrom
docs/aigov-476-ai-gateway-cost-controls

ssncferreira commented Jul 29, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

ssncferreira Jul 30, 2026

Uh oh!

johnstcn Jul 30, 2026

Uh oh!

jcjiang Jul 30, 2026 •

edited

Loading

Uh oh!

coderagents Bot commented Jul 30, 2026 •

edited

Loading

Uh oh!

ssncferreira Jul 30, 2026

Uh oh!

johnstcn Jul 30, 2026

Uh oh!

ssncferreira Jul 30, 2026

Uh oh!

johnstcn left a comment

Uh oh!

Uh oh!

johnstcn Jul 30, 2026

Uh oh!

johnstcn Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

ssncferreira commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Uh oh!

linear-code Bot commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs preview

Uh oh!

ssncferreira Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

johnstcn Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

jcjiang Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderagents Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Check

Updates Needed

Minor

Uh oh!

ssncferreira Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

johnstcn Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

ssncferreira Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

johnstcn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

johnstcn Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

johnstcn Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ssncferreira commented Jul 29, 2026 •

edited

Loading

github-actions Bot commented Jul 29, 2026 •

edited

Loading

jcjiang Jul 30, 2026 •

edited

Loading

coderagents Bot commented Jul 30, 2026 •

edited

Loading