[DOCS] /usage docs omit the current limits-usage breakdown categories

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/costs

Section/Topic

Using the /usage command

Current Documentation

The docs currently say:

The Session block in /usage shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so the session cost figure isn't relevant for billing purposes. Subscribers see plan usage bars and activity stats on the same screen. The /usage command provides detailed token usage statistics for your current session. The dollar figure is an estimate computed locally from token counts and may differ from your actual bill.

The command reference also says:

/usage | Show session cost, plan usage limits, and activity stats. See the cost tracking guide for subscription-specific details. /cost and /stats are aliases

And the weekly digest still says:

/usage now shows what's driving your limits: parallel sessions, subagents, cache misses, and long context, each with a percentage of your last 24 hours and a tip to optimize it.

What's Wrong or Missing?

Changelog v2.1.149 says /usage now shows a per-category breakdown of what's driving limits usage for skills, subagents, plugins, and per-MCP-server cost.

The current docs do not explain that breakdown anywhere in the main /usage reference. The costs guide and commands reference still describe /usage only in general terms, so readers have no documentation for the newer attribution view or what the categories mean.

There is also stale documentation drift: the Week 16 digest still describes a different breakdown (parallel sessions, subagents, cache misses, and long context), which no longer matches the v2.1.149 changelog description.

Suggested Improvement

Update the /usage documentation to describe the current limits-usage breakdown explicitly.

At minimum:

1. Add a short subsection under https://code.claude.com/docs/en/costs explaining that /usage includes a per-category limits breakdown.
2. Name the current categories called out in v2.1.149: skills, subagents, plugins, and per-MCP-server cost.
3. Clarify that this breakdown explains what is driving subscription limits usage, not just the current session's token estimate.
4. Update the /usage row in https://code.claude.com/docs/en/commands to mention the attribution breakdown.
5. Correct or annotate older /usage digest copy that still lists the previous categories.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/costs | Main /usage documentation only describes session token stats, plan usage bars, and activity stats |
| https://code.claude.com/docs/en/commands | /usage command reference omits the newer per-category breakdown |
| https://code.claude.com/docs/en/whats-new/2026-w16 | Older /usage feature description still lists a different set of drivers |

Total scope: 3 pages affected

The changelog entry introducing the current docs gap is from v2.1.149.