## ADDED Requirements

### Requirement: Per-report usage capture

The system SHALL capture the actual usage of every evaluation that calls the
analysis agent from the agent's own reported usage — the Claude Code CLI JSON
output (`total_cost_usd` plus token usage) for the default transport, or the API
response usage for the alternate — not from estimates. Captured fields SHALL
include, where the transport reports them, token counts, model used, and a reported
cost. When the transport runs on a subscription rather than metered billing, the
reported marginal cost MAY be zero or near-zero; the system SHALL record what the
transport reports.

#### Scenario: Usage recorded for a completed report
- **WHEN** an evaluation completes an agent call
- **THEN** the system records the report's token counts, web-search count, model,
  ticker, and timestamp

#### Scenario: Usage captured on partial results
- **WHEN** an agent call fails after consuming tokens (e.g. a mid-stream error)
- **THEN** the usage consumed up to that point is still recorded

### Requirement: Cost computation from a configurable price table

The system SHALL compute each report's cost from captured usage and a configurable
price table (per-model input/output/cache token prices and per-search price).
Prices SHALL be editable via configuration so provider price changes require no
code changes.

#### Scenario: Report cost computed
- **WHEN** a report's usage is captured
- **THEN** the system computes its cost using the configured price table and stores
  the cost alongside the usage

#### Scenario: Unknown model priced safely
- **WHEN** a report uses a model absent from the price table
- **THEN** the system flags the cost as unpriced rather than recording zero

### Requirement: Spend aggregation

The system SHALL maintain a running month-to-date total spend and SHALL expose
per-report cost history. The spend record MAY use lightweight local storage; a
full database is out of scope for this change.

#### Scenario: Month-to-date total available
- **WHEN** a new report's cost is recorded
- **THEN** the month-to-date total reflects the new report
- **AND** the per-report history includes the new entry

#### Scenario: Month boundary resets the running total
- **WHEN** the calendar month changes
- **THEN** the month-to-date total starts from zero for the new month
- **AND** prior months' totals remain available in history

### Requirement: Monthly budget guard

The system SHALL enforce a configurable monthly budget. When month-to-date spend
crosses a configurable soft threshold (default 80% of budget) the system SHALL warn
but still allow evaluations. When spend reaches the budget cap the system SHALL
block new evaluations and return a clear message rather than silently proceeding.
A disabled/zero budget SHALL mean no enforcement.

#### Scenario: Soft-threshold warning
- **WHEN** month-to-date spend crosses the soft threshold but is below the cap
- **THEN** the system allows the evaluation and surfaces a budget warning with the
  current spend and remaining budget

#### Scenario: Hard-cap block
- **WHEN** month-to-date spend has reached the configured cap
- **THEN** the system blocks new evaluations and returns a message stating the cap
  was reached and how to raise or disable it

#### Scenario: Deep-dive gated at the cap
- **WHEN** a deep-dive (Fable 5) evaluation is requested and the projected cost
  would exceed the remaining budget
- **THEN** the system blocks it and explains the remaining budget

#### Scenario: Guard disabled
- **WHEN** the monthly budget is set to zero or disabled
- **THEN** evaluations proceed without budget enforcement

### Requirement: Cost visibility in the UI

The system SHALL display each report's cost in the report view and SHALL surface
month-to-date spend against the configured budget in the app.

#### Scenario: Report cost shown
- **WHEN** a report renders
- **THEN** its computed cost is shown in the report view

#### Scenario: Budget status shown
- **WHEN** the app is in use
- **THEN** month-to-date spend and remaining budget are visible