[czj]

The README and the home page were written for people who already use the browser gem. Someone who has never heard of either had no definition of a user agent, met a 120-line method list before learning what the gem is for, and a home page whose headline was "Same API as browser, faster".

Both now open with what Agentry does and what a User-Agent header is, then why to pick it, how to install it and a first example with its results. Reference material the guide and the Bots page already hold is summarized in a sentence with a link instead of being repeated.

• README follows a reader's path: what it is, why Agentry (measured numbers kept exactly), installation, a first example, then bots, verified crawlers, Cloudflare and Client Hints, Accept-Language, middleware, cache, switching, performance, testing, development and license.
• Reference moved to links: the full predicate list, Internet Explorer and Safari notes, aliases, the modern browser recipe and matcher removal live on guide.html and bots.html already. Cache, limits and eager_load! stay in the README, since the site does not cover them.
• New testing section: says in plain words how browser's suite and the 20,328 user agent corpus check every answer.
• Home page lede and order: new title, meta and og descriptions, byline "Who sent this request?", an intro sentence, Quick start moved above the numbers with return values, "What changes" renamed "Why Agentry" with a verified crawlers card in place of the cache card.

Checks

Every example result in the README and on the home page was run against lib/ (Safari 18.1 on iPhone, GPTBot, Claude-User, Googlebot with a Google IP, Cloudflare headers). script/highlight_docs.rb --check and script/render_docs.rb --check pass. Playwright at 1280 px and 390 px shows no horizontal scroll.