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

Why

The current renderer shows three quota rows (5-hour, 7-day, month), but the monthly window is an awkward fit: the API only returns max_flows and max_value_usd for it — no used_* fields — so the monthly progress bar is always empty and the used columns show —. Visually this looks like a bug or missing data. Since the monthly row is really just a cap/limit rather than a live-usage window, it belongs below the usage bars as a compact one-liner, not as a peer row next to the two real progress windows.

What Changes

• Drop the month row from the three-progress-bar block. The renderer now shows only the 5 hour and 7 day rows with bars.
• Add a compact "Monthly cap" summary line below the "Tokens consumed" line, formatted as Monthly cap: <max_flows> flows · $<max_value_usd> (e.g. Monthly cap: 34560 flows · $1134.33).
• Update the human-mode snapshot tests and the README ASCII sample accordingly.
• No change to JSON output — quota_monthly is still passed through in the API response verbatim.

Capabilities

New Capabilities

Modified Capabilities

• subscription-usage: the "Render three quota windows per account" requirement becomes "Render two quota windows per account"; the "Display token USD value consumed per account" requirement's prose is adjusted from "three quota rows" to "quota rows"; a new "Display monthly cap" requirement is added.

Impact

• internal/render/render.go — remove the month entry from the progress-bar row builder; add a new line emission after the tokens-consumed line.
• internal/render/render_test.go — drop the — / 34560 flows and n/a assertions; add an assertion for the new Monthly cap: line.
• README.md — update the ASCII sample to reflect two progress bars plus the monthly cap line.
• No API, config, or CLI-flag changes; no effect on exit codes or JSON mode.