How Every Number Is Calculated

Dashboards go wrong when a number looks authoritative and the method is invisible. AI Stats ships how-calculated drawers and adapter health so every figure can answer three questions: what was measured, which source could supply it, and what happens when the source cannot.

Every primary metric should expose a short method note: the definition, the unit, the adapter capability required, and the failure mode when the export omits the field. If you cannot open a drawer, treat the number as incomplete documentation even if the digit looks confident.

The drawer is not marketing copy. It is the same contract the adapter health panel and the capability matrix use. When those disagree, the product has a bug, and the drawer is how you notice.

A green total built from a red adapter is a contradiction. Health surfaces exist so you can see whether Codex tokens, Cursor sessions, or a consumer chat export actually contributed. Compare those states before you explain a week to anyone else.

Health is not a separate page you visit after the chart confuses you. It is part of reading the chart. If an adapter is degraded, every tile that depends on it inherits that caveat even when the digit still renders.

When a consumer chat export omits tokens or cost, the tile stays Unavailable. It does not become 0. Zero would invent a trend. Unavailable preserves the gap and points at the capability matrix reason.

That rule also protects comparisons. A week with three Unavailable days is not a quieter week; it is a week with missing evidence. Plotting zeros would invent a recovery story the file never supported.

Missing days break sparklines instead of plotting zero. Comparison views keep blocked rows instead of dropping them. Those behaviours match the methodology centre: unreported is not measured.

If a sparkline looks smooth after an incomplete import, something silenced a gap. Prefer the broken line. Prefer the blocked row. Prefer the drawer that names the missing capability over a polished chart that lies by omission.

1. Open the how-calculated drawer for that tile.
2. Check adapter health for the sources in range.
3. Confirm the date range and saved view filters.
4. Re-import only if the receipt shows a partial or failed run.
5. Export a snapshot if you need a durable explanation.

Write what you saw. A teammate should be able to repeat the same five steps without asking you which menu you meant. If they cannot, the article or the UI label is unfinished.

Some overview layouts look like maps because they arrange providers as a constellation. They are not geographic maps. They do not claim a country, a ping, or a datacentre story. Treat them as relationship diagrams for adapters and coverage, not as travel maps.

It refuses vendor scoreboard language. It refuses estimated tokens presented as counted tokens. It refuses cost stories built on fields the file never contained. It refuses treating Unavailable as a soft failure you can ignore when the presentation looks fine.

How-calculated drawers explain derivation. Import receipts explain arrival. Read both when a total moves. A correct formula applied to a duplicated import still produces a wrong week. A clean import with a misunderstood unit still produces a wrong story.

When an adapter gains or loses a field, update the drawer text in the same change set. Dated reviews are claims about prose, not about builds. Do not bump an updated date for whitespace. Do bump it when the method note changes.

Keep media for this article on blog paths: poster, captions, transcript, and the opt-in film. Those assets explain the feature. They are not a reason to edit advertising configuration.

A token total that includes a provider whose adapter health is red. A cost tile that treated missing cost as zero for three days, then suddenly "jumped" when the field appeared. A comparison saved view that dropped blocked rows so the delta looked smaller. A sparkline that connected across a gap as if the missing days were quiet rather than unknown.

Each of those failures looks like insight until you open the drawer and the health panel. The product rule is the opposite of polish-first: prefer the awkward honest state.

Read the definition once without looking at the digit. Then look at the digit. Then look at adapter health. Then look at the date range. If any of those four disagree with the story you were about to tell someone, stop and write the disagreement down before you share the chart.

That habit is the whole point of shipping how-calculated surfaces. The digit is not the deliverable. The explainable digit is.

Not every provider export carries every field. Not every field is stable across product versions. Not every constellation layout is a map. The methodology centre exists to keep those limits visible after the first week of excitement fades.

If a teammate cannot find the drawer for a tile you care about, treat that as a product defect in discoverability, not as a documentation problem alone.

Suppose a coding-agent export covers Monday through Friday and omits weekend rows entirely. The sparkline should show a break, not a flat zero weekend. The comparison against last week should keep a blocked or unavailable marker for the days the file never claimed. The how-calculated drawer for active time should say whether weekends were expected.

Now suppose a second import adds Saturday only. The receipt should show one day accepted and name what was skipped. Replay of the second file alone should not rewrite Monday through Friday. Undo of the second import should restore the Friday-ending sparkline without inventing Saturday zeros.

That is the bar. If your current build cannot show those states, do not paper over them in a screenshot for stakeholders.