docs(usage): add cost tracking guide

[SantiagoDePolonia]

Summary

Adds a Cost tracking docs page (docs/features/cost-tracking.mdx, wired into docs.json under Features) and regression tests that pin the behaviour it describes. Follow-up to #439 / issue #435, which exposed that the cost model is non-obvious and undocumented.

The page covers

• Estimates, not billing — a <Warning> up front: figures come from catalog pricing and provider-reported token counts and can differ from a provider's bill (promotions, rounding, cache rules, currency, plan discounts). Provider dashboard is the source of truth.
• How costs are estimated — input/output per-MTok plus cached/reasoning/audio breakdowns; provider-reported costs (OpenRouter credits, xAI ticks) preferred when present; cost_source per row.
• Where pricing comes from — overrides → config.yaml → catalog.
• Override pricing — Models page → Pricing override editor (USD). Two screenshot placeholders are left here (see below).
• Dashboard totals — Estimated Cost (live spend, cache excluded) vs Saved Cost; --- means unknown, not $0.
• Recalculate stored costs — enabled by default (USAGE_PRICING_RECALCULATION_ENABLED=true), typed confirmation, scoped to the current filters. A <Warning> documents that recalculation clears the cost of rows whose model no longer resolves to pricing rather than preserving it.

Regression tests (validate what the guide documents)

• internal/usage/dashboard_cost_validation_test.go — full chain (extractor → SQLite store → reader): Estimated Cost excludes cache hits, per-model totals, Saved Cost from the cache overview; cached discounts apply for both nested (prompt_cached_tokens) and DeepSeek top-level (prompt_cache_hit_tokens) reporting.
• internal/usage/recalculate_pricing_issue435_test.go — recalc corrects a stale pre-fix cached cost (and clears its caveat) and nulls a row whose model lost pricing, counting it as WithoutPricing.

Screenshots — action needed

I could not capture the two override screenshots (the Chrome extension wasn't connected in this session), so the page has two clearly-marked placeholder slots in the Override pricing section, each with a TODO comment containing the ready-to-paste <img> snippet. To fill them: run the dashboard, open /admin/dashboard/models, capture the Models row action and the Pricing override editor, save as docs/features/pricing-override-models.png and docs/features/pricing-override-editor.png, and replace the placeholder <div>s.

Checks

Pre-commit passed: mint validate, make test-race, make lint, go mod tidy.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added a new guide covering tracked request-cost estimation, pricing override precedence/behavior, estimated vs. saved dashboard semantics, and the “Recalculate stored costs” workflow.
  • Updated the Documentation Features navigation to include the new cost tracking page.

• Bug Fixes

  • Improved dashboard/overview cost reporting reliability by adding end-to-end validation of cost aggregation, cached/live spend separation, and saved-cost reporting.
  • Added test coverage ensuring stored costs are recalculated correctly, including clearing stale cached-cost caveats and setting costs to unknown when pricing can’t be resolved.

[coderabbitai]

Warning

Review limit reached

@SantiagoDePolonia, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 18 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2bc57c62-60d1-40d1-a0d2-32aa70affc39

📥 Commits

Reviewing files that changed from the base of the PR and between 3bfb328 and 7a4d6e8.

📒 Files selected for processing (2)

• internal/usage/dashboard_cost_validation_test.go
• internal/usage/recalculate_pricing_issue435_test.go

📝 Walkthrough

Walkthrough

Adds a cost-tracking documentation page and nav entry, plus two SQLite-backed Go tests covering dashboard cost aggregation and stored-cost recalculation behavior.

Changes

Cost Tracking Docs and Tests

Layer / File(s)	Summary
Cost tracking documentation docs/docs.json, docs/features/cost-tracking.mdx	New MDX page documenting estimation rules, cost_source, pricing resolution priority, override configuration, dashboard totals semantics (--- vs $0), and the recalculation workflow; the page is added to the Features nav.
Dashboard cost aggregation end-to-end test internal/usage/dashboard_cost_validation_test.go	TestDashboardCostAggregation_EndToEnd builds two live and one cache-hit UsageEntry (xiaomi and deepseek), persists them to in-memory SQLite, and asserts GetSummary excludes cache hits, GetUsageByModel returns per-model totals, and GetCacheOverview reports correct saved cost.
RecalculatePricing stale-cost correction test internal/usage/recalculate_pricing_issue435_test.go	TestSQLiteStoreRecalculatePricing_CorrectsStaleCachedCosts seeds one stale-caveat row and one no-pricing row, runs RecalculatePricing, and asserts recomputed costs with cleared caveat for the resolved row and SQL NULL costs for the unresolved row.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ENTERPILOT/GoModel#144: Related dashboard usage pipeline changes add and aggregate cost fields that the new end-to-end cost test exercises.
• ENTERPILOT/GoModel#439: Related cached-token pricing handling changes are directly exercised by the dashboard aggregation and recalculation tests.

Poem

🐇 I hopped through costs with a twitchy nose,
Counted cached tokens and pricing rows.
“Recalculate!” sang the rabbit in glee,
While SQLite kept the numbers tidy and free.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a cost tracking documentation guide under docs/usage.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/cost-tracking

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[mintlify]

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

Project	Status	Preview	Updated (UTC)
gomodel	🟢 Ready	View Preview	Jun 29, 2026, 5:36 PM

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

[greptile-apps]

Confidence Score: 5/5

The documentation and regression-test additions appear safe to merge.

The changed files are limited to a new guide, docs navigation, and targeted tests for the documented cost-tracking behavior, with no review comments requiring code changes.

T-Rex Logs

What T-Rex did

• Compared the cost-tracking docs before and after states to verify the route file exists and the Features navigation appears.
• Reviewed the regression tests and integration package evidence to confirm new tests are declared and pass on head.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs(usage): add cost tracking guide" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@internal/usage/recalculate_pricing_issue435_test.go`:
- Around line 20-24: The SQLite test setup in the db initialization block should
be pinned to a single connection so the in-memory database is shared across all
operations. Update the test around sql.Open in RecalculatePricing-related setup
to call db.SetMaxOpenConns(1) (or use a shared-cache in-memory DSN) before
running WriteBatch, RecalculatePricing, and the validation queries, so they all
use the same connection and see the same tables and rows.

🪄 Autofix (Beta)

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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1e1cd918-b38b-43b2-b30c-11e3d1d271ef

📥 Commits

Reviewing files that changed from the base of the PR and between 77ca8e5 and 4f824e3.

⛔ Files ignored due to path filters (2)

• docs/features/pricing-override-editor.png is excluded by !**/*.png
• docs/features/pricing-override-models.png is excluded by !**/*.png

📒 Files selected for processing (4)

• docs/docs.json
• docs/features/cost-tracking.mdx
• internal/usage/dashboard_cost_validation_test.go
• internal/usage/recalculate_pricing_issue435_test.go