[thrawn01]

Purpose

The README explained how groupcache works only deep in its internals section, so a visitor couldn't quickly see why they'd pick it. A new "Design" section near the top now tells the story: one owner per key, loads through your Getter, one load per key, local fallback, main and hot caches, cluster-wide Set/Remove/RemoveKeys, expiry on read, pluggable caches and transports, OpenTelemetry, and many instances per process. Each pattern links to the code behind it.

There are no planned features to show. The repo has no designed, unshipped work, and the ticket author confirmed they have none, so the section covers only what ships today.

It also fixes the hot cache size. The hot cache is 1/8 of the group's max bytes (1/7 of the main cache), not 1/8 of the main cache.

Implementation

• README.md: replaced "Why Use Groupcache?" and "How It Works" with "Design". The old text said owned keys are served from the hot cache, which is wrong, since the hot cache holds copies of other peers' keys.
• "The Cache Loading process": steps 1 and 2 now follow the code's order (main cache, then hot cache), and the RPC fallback step points to the exceptions in Design.
• "groupcache.Cache": hot cache size corrected, and the main cache is described as holding keys the peer loaded or received through Set(). RemoteSet writes to the main cache on every peer.

How it was checked: a fresh reviewer compared every behavior claim against the code and found five problems (main cache described as owned-only, fallback exceptions, "runs once" overstated, "callers never fill the cache", and the step order). All are fixed in this PR. Links in Design resolve to existing files. Nothing was built or run, since only README.md changed. I did not re-review after the fixes.

Fixes ENG-566