(CODUX-228) Integrate the Cost mode into Stats

[numnx]

🧩 Task: Integrate the Cost mode into Stats

Automated task PR opened by Code UX for T07.

📋 Summary

Sprint: Sprint 228 · Stats Cost analytics · Task: T07

Add a trustworthy, accessible Cost analysis mode to Stats that exposes provenance-aware spend, averages, token and spend allocation, canonical per-sprint and per-task detail, model and execution-purpose breakdowns, and resilient navigation and refresh states across every existing Stats time range.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-14 03:02:48 UTC
Finished	2026-07-14 03:05:58 UTC
Duration	3m 9s

📊 Token Usage

Metric	Value
Input tokens	345,135
Cached input tokens	14,172,928
Output tokens	34,228
Total tokens	14,552,291
Invocations	3
Tool calls	117
Active time	20m 37s

Included usage estimate (subscription/local login): $9.84

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Deliver the complete Cost subcategory alongside Trend, Composition, Models, Providers, Ledgers, and System using the existing Stats snapshot lifecycle.

## Scope
- Create `dashboard/src/v2/pages/stats/components/cost/CostStudio.tsx`
- Create `dashboard/src/v2/pages/stats/components/cost/CostStudio.module.css` if composition-only layout styles are needed
- `dashboard/src/v2/pages/stats/components/stats-ui-primitives.tsx`: `StatsVisualMode` and `ViewToggle`
- `dashboard/src/v2/pages/stats/components/StatsPageHero.tsx`: mode labels and descriptions
- `dashboard/src/v2/pages/stats/StatsPage.tsx`: mode labels and metric-region naming
- `dashboard/src/v2/pages/stats/use-usage-chart-state.ts`: valid persisted modes and project-scoped restoration
- `dashboard/src/v2/pages/stats/components/AnalysisStudioSection.tsx`: Cost metadata, empty state, and studio routing
- `dashboard/src/v2/components/stats/TopCardsModeRenderer.tsx`: Cost summary metric deck
- Add `tests/dashboard/stats/StatsPage.cost.test.tsx`
- Update `tests/dashboard/stats/TopCardsModeRenderer.test.tsx`, `tests/dashboard/v2/stats-page-shell.test.tsx`, `dashboard/tests/dashboard/stats/StatsPage.accessibility.test.tsx`, and relevant Stats visual regression fixtures
- Update `docs/dashboard/design-system-stats.md` and `docs-web/user/dashboard/stats.md`

## Implementation Requirements
1. Compose `CostStudio` by deriving the T03 view model once and rendering the overview/trend, allocation, and entity-ledger components from T04-T06 in a coherent responsive hierarchy.
2. Add Cost after Composition in every Stats mode registry, label map, description map, persisted-mode validator, keyboard sequence, context rail, metric-region label, and `AnalysisStudioSection` branch without renaming or reordering unrelated modes.
3. Add a Cost metric deck with total spend, average per task, average per sprint, blended cost per million tokens, and pricing coverage; reuse adaptive formatting and never label unpriced zero totals as free.
4. Preserve existing project/range fetching, request cancellation, silent-refresh stale data, retry, no-project, loading, error, custom-range validation, realtime invalidation, and project-scoped mode persistence behavior.
5. Add page-level integration tests that select Cost by click and keyboard, restore it from storage, render all child sections from a realistic API snapshot, preserve cached Cost content during refresh, and cover empty, partial, fully unpriced, legacy unknown, and legitimate zero-cost snapshots.
6. Extend accessibility coverage for mode naming, focus order, chart alternatives, tab and sort controls, live announcements, long content, reduced motion, and the absence of unnamed controls or horizontal overflow at narrow widths.
7. Update canonical design documentation and the public Stats guide with navigation order, metrics, averages, allocation definitions, canonical sprint behavior, pricing provenance, zero-versus-unpriced semantics, and operator guidance for model pricing; do not add a new docs page or index entry for this in-page mode.

## Constraints
- Consume the existing `/api/projects/:projectId/stats` hook and additive T01 contract; do not create another request, route, settings store, or local protocol.
- Preserve all existing Stats modes and their tests, and keep Cost mode selection scoped to the same per-project storage key.
- Reuse repository design tokens and local primitives, add no dependency, and maintain accessible light/dark desktop and mobile behavior.
- Do not claim pricing completeness when coverage is unknown or partial, and do not expose provider secrets or raw usage payloads.

## Verification
- Run `pnpm exec vitest run dashboard/src/v2/pages/stats/__tests__/cost-insights.test.ts dashboard/src/v2/pages/stats/__tests__/CostOverviewPanel.test.tsx dashboard/src/v2/pages/stats/__tests__/CostAllocationPanels.test.tsx dashboard/src/v2/pages/stats/__tests__/CostEntityLedgers.test.tsx tests/dashboard/stats/StatsPage.cost.test.tsx tests/dashboard/stats/TopCardsModeRenderer.test.tsx tests/dashboard/v2/stats-page-shell.test.tsx dashboard/tests/dashboard/stats/StatsPage.accessibility.test.tsx`.
- Run `pnpm run test:dashboard`, `pnpm run typecheck:dashboard`, `pnpm run check:docs-web`, and `pnpm run build`.
- Start `pnpm run dev` and verify `http://localhost:4444/stats` in light and dark themes at desktop and mobile widths, including keyboard-only navigation, range changes, refresh with stale data, empty and unpriced states, and no console errors or horizontal page scrolling.

🌿 Branch Info

Base: feature/CODUX-228-stats-cost-analytics
Head: task/feature-codux-22-t07-codex-62dddfd2-mrk1prg3

---

🤖 Generated by Code UX