docs: Refactor README positioning to highlight cost savings, zero-overhead UX, and visual proof

[fajarhide]

Feature Idea

Overview

Currently, the OMNI README provides deep technical details on how the distillation engine and ledger work. However, for new developers or teams considering adoption, the core financial and UX benefits can be made more immediate.

Refactoring the main documentation will help articulate OMNI's value proposition faster and reduce friction during initial evaluation.

Proposed Changes

1. Value-First Headline & Hooks:
   • Emphasize direct outcomes early: context window optimization, lower API bills for agentic sessions (e.g., Claude Code / Codex / Aider), and elimination of context degradation.
2. Visual Before-and-After Comparisons:
   • Add clear side-by-side terminal screenshots or ASCII diagrams contrasting a noisy output (cargo test / docker build) vs. distilled OMNI output.
3. Interactive ROI / Savings Callout:
   • Highlight real-world token savings upfront alongside the existing benchmarks to instantly signal utility to developers managing heavy CLI agent workflows.

Tasks

• Draft concise value-proposition section at the top of README.md.
• Create visual assets (SVG/PNG or clean code blocks) showing side-by-side terminal reduction.
• Add a "Why OMNI?" section targeting developer agent workflows.

Why is this needed?

The current documentation focuses heavily on technical implementation (ledger mechanisms, RewindStore, schemas). New users need to instantly understand the business and workflow value within 5 seconds of landing on the repository, rather than parsing internal architectural details first.

​## What is the token-savings impact or use-case?

​Use-case: Developers evaluating OMNI to reduce LLM API overhead across agentic sessions.
Impact: Clearly communicates the 24.1% average session-wide repetition reduction (up to 97.2% on duplicate file reads and 93% on build output) directly upfront. Converting immediate understanding into adoption directly lowers multi-turn agent input token costs for users.

Alternatives Considered

No response

[fajarhide]

Triaged priority: low, stage: later, and the timing matters: yesterday this repository
corrected its own published ledger figure from 4.9% to 3.0% (#760, #761), because the
benchmark had been measuring with the ledger's guards switched off.

So "highlight cost savings" and "visual proof" are the two asks to be most careful with
here. The corpus figure a reader can verify is 3.0% with the ledger and 1.4% from the
filters, aggregate, and the strong true sentence is the per-class one rather than either
of those. docs/internal/plan.md §11 and the copy doctrine in the PM skill both say the
same thing: reframing is re-ordering and re-emphasis, never new arithmetic, and a
flattering sentence gets the same scrutiny as a flattering number.

Two of the proposed changes already have homes:

• the tier matrix and the host-specific notes are in docs/website/src/reference/agents.md
• docs/website/src/develop/benchmarks.md is the archive that keeps every figure with its
  corpus, including the unflattering ones, which is where "visual proof" has to point

What would genuinely help, and is not written down anywhere yet: the README leads with a
mechanism (what the ledger does) before it leads with a class (file re-reads, where the
bytes are). That is a re-ordering, it needs no new number, and it survives the doctrine.

Kept in later rather than refused: the ask is reasonable, the sequencing is not. A
positioning pass wants the figures to have settled first, and they settled yesterday.