zenmux-usage-cli/openspec/changes/archive/2026-04-22-simplify-monthly-display/specs/subscription-usage/spec.md

MODIFIED Requirements

Requirement: Render two quota windows per account

In human output mode the CLI SHALL render, for each resolved account, one labeled row per rolling window — 5 hour and 7 day. Each row MUST include a fixed-width progress bar, the usage percentage to two decimals, the used-vs-max flows, and the used-vs-max USD value. Bars MUST be color-coded by usage band: green below 60%, yellow from 60% through 85%, red above 85%. The monthly quota MUST NOT be rendered as a third progress-bar row; it is emitted separately by the "Display monthly cap" requirement.

Scenario: Healthy 5-hour window

• WHEN the API returns quota_5_hour.usage_percentage = 0.0715, used_flows = 57.2, max_flows = 800, used_value_usd = 1.88, max_value_usd = 26.26 for an account
• THEN that account's block contains a row labeled 5 hour, a green-colored bar roughly 7% filled, 7.15%, 57.2 / 800 flows, and $1.88 / $26.26

Scenario: No monthly progress row rendered

• WHEN an account is rendered in human mode
• THEN the output MUST NOT contain a row labeled month inside the progress-bar block, and MUST NOT contain an em-dash (—) placeholder or n/a percentage inside the bar rows

Scenario: Color disabled via flag

• WHEN the user runs zenmux-usage --no-color
• THEN no ANSI color escape sequences appear in the output

Scenario: Non-TTY output is automatically plain

• WHEN stdout is piped or redirected to a file
• THEN the CLI omits ANSI color escape sequences regardless of the --no-color flag

Requirement: Display token USD value consumed per account

Below each account's quota rows the CLI SHALL print a summary line labeled "Tokens consumed (estimated USD value)" showing the used_value_usd from the 7-day window for that account, formatted as USD to two decimals.

Scenario: 7-day used value present

• WHEN an account's quota_7_day.used_value_usd = 13.66
• THEN that account's summary line reads Tokens consumed (estimated USD value): $13.66

ADDED Requirements

Requirement: Display monthly cap

Below the "Tokens consumed" summary line and above any "Next reset" line the CLI SHALL, in human output mode, emit a one-line summary of the monthly quota cap using quota_monthly.max_flows and quota_monthly.max_value_usd. The line MUST be formatted as Monthly cap: <max_flows> flows · $<max_value_usd> with max_flows printed without trailing zeros and max_value_usd formatted as USD to two decimals.

Scenario: Monthly cap present

• WHEN an account returns quota_monthly.max_flows = 34560 and quota_monthly.max_value_usd = 1134.33
• THEN the output contains a line Monthly cap: 34560 flows · $1134.33

Scenario: Cap line placement

• WHEN the human-mode block is rendered for an account
• THEN the "Monthly cap:" line appears after the "Tokens consumed (estimated USD value):" line and before the "Next reset:" line (when a reset line is emitted)

Scenario: JSON mode unchanged

• WHEN the user runs zenmux-usage --json
• THEN no "Monthly cap" line is injected into the JSON output; the quota_monthly field from the API response is the only monthly representation