docs: explain what Cortex shows and why it is worth running — interpreting the metrics and the value case
@mrsabath is already working on this.
Since Sep 10, 2026.
- Dominant language
- Go
- Stars
- 13
- Forks
- 40
- Avg merge
- 12h 17m
- Merged PRs (30d)
- 156
Description
Feature Description
The docs will say how to install Cortex and how to drive it, but not what to do with what you
see. Someone looking at a session's token counts, its cache-read versus cache-write split, a cost
figure and latency percentiles has no page telling them what any of it means, which numbers
matter, or why leaving Cortex running is worth it.
This backs exit criterion 5 of the v0.9.0 release: a new user can self-serve on a typical
workstation, using the docs alone.
Proposed Solution
- What Cortex is for, readable before installing: what it shows you that you cannot
otherwise see - The value case in concrete terms — what decisions the numbers support: spotting an
expensive prompt, seeing whether caching is working, catching a runaway session, deciding
whether pruning is worth enabling - How to read a session: what each token category means, and why cache-read and cache-write
are priced differently rather than being one number - How to read cost: what is included, what is estimated, and where the rates come from
- How to read latency: time to first token versus total response time, and what the
percentiles actually tell you - How to read the tool-pruning savings figure, including what a zero means for an agent with
no tool inventory - A worked example on a real session, with real output rather than paraphrase
- Verified by someone outside the team reading only the docs
Additional Context
Part of the Cortex v0.9.0 release. Complements #959 (the first-run path — how to get there) and
#960 (troubleshooting — what to do when it breaks); this issue is what the results mean once you
are there, and why they are worth having.
Depends on the metrics work landing: #950, #951, #952.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.