Refresh browser pool guides and standardize on "browser pools"

[andrewleesteele]

Summary

Browser pools are the thing most production workloads want on day one, but the docs don't lead anyone there: the concept is called "Reserved Browsers" in the sidebar, it's filed under Advanced, there's no quickstart, and the Create page never mentions it.

This PR does four things:

1. One name: "browser pools." The API (/browser_pools), SDKs (browserPools / browser_pools), CLI (kernel browser-pools), and dashboard all already use it, so the docs were the outlier. Renamed the sidebar group Reserved Browsers → Browser Pools and dropped "reserved browsers" as a product name across the docs. Where "reserved" was doing real work (concurrency accounting), it's reworded to say the thing directly — "a pool sized to 40 browsers uses 40 of your limit." Historical changelog entries are left alone.

2. Moved the pool guides from Advanced to Basics, next to the concurrency-limits page they interact with. No URLs changed, so no redirects are needed.

3. New Browser Pools Quickstart — create a pool, acquire/drive/release a browser, watch available_count to size it, plus a "before you go to production" section covering the three behaviors that differ from on-demand browsers (timeout only runs while acquired, update doesn't reconfigure existing browsers, pool profiles are read-only). TypeScript, Python, Go, and CLI examples throughout. It's now the first page in the group; Overview is positioned as the full API surface.

4. Pools are pitched from the pages new users actually land on. Added an "On demand or from a pool" section to introduction/create with the create-once/acquire-per-task pattern, a pointer from the home page's scaling section, and a pointer from introduction/scale to the quickstart for mechanics. Every one of these leads with the fact that idle pooled browsers aren't billed — the most common misconception, and the one that most often flips someone from "pools sound expensive" to "why wouldn't I use these."

Also added a Browser Pool entry to the Concepts page.

Verification

• docs.json is valid JSON and every page path in the navigation resolves to a file.
• Checked every internal link and heading anchor in the changed files with a script — all resolve, including the renamed #create-a-pool anchor (was #create-a-pool-of-reserved-browsers, referenced from two places).
• MDX component tags and code fences balance in all changed files.
• API/CLI details verified against the published OpenAPI spec and the CLI reference — notably the 25% default fill rate, the 600s default timeout, and that size is required on update.
• I could not boot mint dev in my environment, so the pages aren't visually confirmed. Worth a look at the preview before merge.

Open questions

• Placement within Basics. I put Browser Pools after Headless and before Projects. Easy to move up if it should be more prominent.
• Changelog. Not touched — entries look batched weekly, so this belongs in the next batch rather than a new one-off block.
• Two things outside this repo still use other names, worth follow-ups: the public pricing page describes Start-Up concurrency as "on-demand and pre-configured," and three changelog links point at /browsers/pools, which has no page (they need /browsers/pools/overview).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Error		Jul 28, 2026 2:36am

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Jul 28, 2026, 2:37 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟡 Building	–	Jul 28, 2026, 2:36 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[andrewleesteele]

Note: Hypeship prematurely created this PR...still thinking necessary changes through.