---
name: carbon-stats
description: Show an evidence-qualified, privacy-safe CARBON activity dashboard with commands executed and frequency, tests created and executed, issues found and explicitly verified fixed, biggest issues saved, exact host-supplied tokens and model levels per activity, observed unit costs, evidence leverage, and optional user-baselined time and dollar savings. Use when the user asks for CARBON stats, usage, tokens, costs, savings, productivity, ROI, command history, issue counts, or testing economics.
user-invocable: false
---

# CARBON Stats

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

Generate a branded project-local dashboard from CARBON's durable artifacts and
content-free metrics ledger. Keep observed facts, derived ratios, scenario
estimates, and missing measurements visibly separate.

## Build the snapshot

1. Resolve the current project root.
2. Call `carbon_stats` with `action=summary`. This records only that
   `carbon-stats` ran, then inventories command reports and journey history,
   durable runs, test libraries, evidence manifests, and existing stats events.
3. Use the returned `reportPayload` without inflating or rewriting its numbers.
   Pass it to `carbon_publish_command_report` and open the returned HTML inside
   the coding agent as required by
   [command result reporting](../../runtime/carbon/references/command-result-reporting.md).
4. End with the current host's **Open the CARBON report** link and repeat the
   most useful observed totals plus the largest measurement gaps.

## Evidence rules

- A planned test is not an executed test.
- A found issue is not a fixed issue. Count a fix only when its original finding
  has an explicit verified fix record after re-testing.
- Use exact token, provider, model, model-level, duration, and cost counters only
  when the host or an authoritative tool supplies them. Never estimate token
  counts from prose, output length, filenames, or model pricing.
- Never imply that command volume, token burn, tests created, or issues found is
  product confidence. Recommend `$carbon-confidence` when the user wants a ship
  judgment.
- Exclude CARBON's seeded-defect benchmark from product issue totals.
- The local stats ledger is content-minimized: never write prompts, responses,
  URLs, source text, credentials, screenshots, user identity, or persistent
  cross-project identifiers to it.

## Record exact usage when available

When the current host or an executed tool returns authoritative usage metadata,
call `carbon_stats action=record-usage` with the narrowest matching activity:
planning, discovery, test-creation, execution, evidence-analysis, issue-triage,
fix, re-test, reporting, or other. Include only supplied counters. Record the
exact provider, model, and model level when known; otherwise leave them blank.
Do not block the workflow when usage metadata is unavailable.

After CARBON re-tests the exact original finding and observes the fix, call
`carbon_stats action=record-fix` with its finding ID, run ID, `verified=true`,
and a short non-sensitive verification method. Never use this action merely
because code changed or a developer says the issue is fixed.

## Savings and cost estimates

By default, missing traditional-testing baselines produce **NOT ESTIMATED**.
If the user supplies minutes per test creation, test execution, issue triage,
fix verification, and a loaded hourly rate, pass those as `baseline` for a
one-time scenario. To persist project defaults, show the exact assumptions and
only call `action=configure` with `confirm=true` after explicit approval.

Model pricing is similarly explicit: use recorded cost returned by the provider
or user-supplied per-model rates. Label time and dollar savings as a scenario,
not audited ROI. Cost per test creation and execution require both attributable
cost and matching recorded work; otherwise leave them **NOT MEASURED**.

## Useful dashboard extras

Keep the generated sections for command leaderboard, model mix, activity token
burn, biggest verified issues saved, evidence density, issues per 100 executed
tests, fix-verification rate, active days, command streak, unit economics, and
measurement gaps. These are diagnostic signals, not targets to game.
