Refresh browser pool guides and standardize on "browser pools" (#464)

* Refresh browser pool guides and standardize on "browser pools"

Add a Browser Pools Quickstart, move the pool guides from Advanced to
Basics, and use "browser pools" as the single name for the concept
everywhere in the docs (the API, SDKs, CLI, and dashboard already do).

Push pools as the production path from the Create page, the home page,
and the Scale guide, and lead with the fact that idle pooled browsers
aren't billed.

* Add reuse-isolation, throughput, and profile guidance to pools docs

- Document that reuse: true persists browser state across acquisitions
  (not isolated) and reuse: false is the clean/per-user path, with a
  multi-tenant leak warning.
- Explain why acquiring is faster than browsers.create(): pre-applied
  restart-triggering configs and no create-endpoint rate limit.
- Point the read-only-profile note at the per-user-profiles pattern
  instead of a standalone session.
- Fold two update-semantics FAQ entries into one pointer to the
  canonical Update a pool section; align the fill-rate example with the
  25% default.
- Keep the Browser Pools nav group in Advanced for now.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Remove the browser-pools quickstart, point entry links to the overview

The pools quickstart is being folded into a future unified Kernel
quickstart rather than living as a feature-specific guide. Delete the
page and its nav entry, and repoint the six inbound links
(home, pricing, concepts, create, scale, and the overview callout) to
the browser pools overview.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Reframe home-page pools blurb: production step, not a day-one default

Position browser pools as the step you reach when taking a working
automation to production, after learning to create and drive a browser
— rather than "most production workloads run on them from day one,"
which pushes them before the fundamentals.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fold the browser-pools FAQ into the overview and delete it

Move the one piece of guidance the overview lacked — pool sizing via
available_count — into a Sizing section, and drop the FAQ page. Its
other entries duplicated overview sections (update, reuse, timeout,
profiles) or belonged elsewhere (target-site rate limiting, debugging).
Repoint the auth/profiles link to the per-user-profiles section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Spell out "browser pool" in prose; stop using bare "pool"

Apply the naming rule to cross-page references (home, pricing, projects,
scale, create, proxies, reference, integrations) and the pools overview
intro so the feature is never shortened to "pool" — which collides with
connection pools, IP pools, and socket pools elsewhere in the docs.
Non-browser-pool uses (curl connection/socket pools, proxy IP/ISP pools)
are intentionally left for their own qualifiers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Collapse browser pools to a single page at /browsers/pools

With the FAQ folded in and Chrome policies moved out (#469), the
section is one page. Move browsers/pools/overview.mdx →
browsers/pools.mdx so it serves at /browsers/pools, retitle it
"Browser Pools", and collapse the nav group to a single entry.
Repoint every /browsers/pools/overview link to /browsers/pools, fix a
stale #create-a-pool-of-reserved-browsers anchor, and add a redirect
from the old overview path. Changelog's bare /browsers/pools links now
resolve to a real page.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Disambiguate non-browser-pool "pool" mentions

Qualify the overloaded uses so "pool" is never mistaken for the browser
pools feature: "connection pool" on the curl networking limits, and
"managed proxy pool" / "proxy-pool traffic" on the bot-detection page.
"ISP pool" (auth) and "warm pools" (unikernels, a generic industry
term) are already unambiguous and left as-is.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Soften the pool-sizing threshold and add a Limitations section

Reframe the ~50-concurrency figure as an illustrative point rather than
a gate: a small browser pool is worth it whenever acquisition latency
matters and demand is steady. Add a consolidated Limitations section
(no GPU browsers, one fixed config per pool with start_url the only
per-acquire override, read-only profiles, reserved capacity holds
concurrency slots, plan-gated).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Drop the ~50 threshold from pool sizing guidance

Small browser pools still pay off when acquisition latency matters and
demand is steady, so lead with that rather than a concurrency number.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Rewrite the Scale page around benefit → when-to-use, soften home CTA

Replace the co-equal concurrency/patterns/throughput framing (and its
1-50/50-100/100+ gate) with: why a browser pool (low-latency
acquisition, reserved capacity, higher creation throughput; the
concurrency-limit tradeoff), when to use a pool vs on-demand as
workload signals rather than thresholds, and a sizing pointer to the
pools page. Keep the three architecture patterns, dropping their
numeric when-to-use gates. Soften the home-page CTA to name the
workloads pools suit instead of "almost any production workload."

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Stop describing browser pools as "warm"

Per docs-team feedback, "warm" implies pools run hot and bill for idle
time — the opposite of the actual benefit (idle pooled browsers aren't
billed). Replace with "ready to use" / "pre-provisioned" throughout,
and reframe the pricing line to lead with the no-idle-charge benefit.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Tidy the Browser Pools page description

"browser pools of ready-to-use browsers" doubled "browser(s)"; use
"Pre-configure a pool of ready-to-use browsers for instant acquisition."

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Reword pools intro: configure a set of identical browsers

"configure" reads better than "maintain" for setting up a pool; trim
"identically-configured" to "identical" to avoid doubling "configure."

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Dedupe the Browser Pools page

The page explained the same few facts repeatedly: "config is pre-applied
so acquisition is faster" appeared four times, read-only profiles three
times, update/stale-config semantics three times (including a paragraph
duplicated verbatim two paragraphs later), and refresh_on_profile_update
three times.

- Collapse the intro to two paragraphs and drop the paragraph that
  restated it above the Steps block; trim the Step callouts that
  repeated their own step bodies.
- Merge "Refresh on profile update", "How it works", and "Per-user
  profiles with pools" into one "Profiles with browser pools" section.
- Move the stale-configuration warning to "Update a pool", where it
  belongs, and delete the duplicated update paragraph.
- Replace "Pool configuration options" with a short Configuration
  pointer, and move Sizing up next to the acquire/release lifecycle.

All externally-linked anchors are preserved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Point the profiles cross-link at the whole pools profiles section

The general "how do profiles work with browser pools" pointer landed on
the per-user subsection, skipping the read-only and refresh-on-update
behavior above it. The per-user-specific link further down is unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Flag the profile constraints in the pools intro

Listing profiles alongside stealth, proxies, and viewport implied they
behave the same way. A pool takes one profile, shared read-only, so call
that out where the settings are introduced and link to the details.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Tighten the Browser Pools page to behavior and reference

Apply review feedback: drop the intro's repeat of the settings list,
reword the borrowed/topped-up and "unavailable to everything else"
phrasing, stop naming profiles twice in the same limitation, spell out
that pool capacity comes off the organization's concurrency limit, and
use the documented default viewport in the examples.

Move Timeout behavior under Release, where reuse is discussed, and lead
with the practice: always release, with the timeout as a backstop.
Remove the "let it expire" option for rolling configuration, which
relied on idle sessions timing out.

Lead the profiles section with Managed Auth as the way to fill and
maintain a profile, then the one-identity vs per-task choice. Drop the
thin Configuration section.

Move the walkthrough code out — the full example and the per-user
step-by-step both belong in the quickstart — leaving the behavior and
the constraint behind. The page is 401 lines, down from 616.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Trim the pools page to behavior and the operations that carry it

- Fold profiles into the configuration list as a link, dropping the
  awkward two-constraints sentence; the profiles section covers it.
- Break the second paragraph into shorter sentences.
- Replace the Flush, Get details, List, and Delete sections with a
  single "Managing a pool" table. They were pure call-and-description,
  which the API reference already covers; the table keeps the behavior
  notes (force delete, what flush spares) without four code groups.
  This also absorbs the trailing API reference section.
- Fix the update warning, which still said "three ways" after the
  expire-based option was removed.

Code drops from 57% of the page to 49%, and the page to 290 lines from
616 at the start of review — in line with comparable guide pages, which
all keep per-operation examples for the calls that carry behavior.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Reorder pools sections and trim the limitations to pointers

Sizing sat between Release and Update, splitting the create/acquire/
release walkthrough from the operational sections, and left Profiles
stranded between two of them. Move Profiles up to close out the
"using a pool" block so the page reads as three groups: what it is,
using one, then tuning and operating one.

Three of the five limitations restated content covered later in the
page. Keep the list as an up-front gate but make those bullets point
at their sections instead of explaining again.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Apply review feedback to the pools and pricing pages

- Say what you'd otherwise do instead of "configuring one per task":
  the configuration goes on the pool rather than into every
  browsers.create() call.
- Rework the acquisition paragraph so it flows as prose rather than
  three clipped sentences.
- Frame releasing as a best practice rather than an instruction, and
  drop the reuse aside from the timeout section.
- Trim the Managed Auth mention to a pointer; how it works belongs on
  the auth pages.
- Put per-user profiles above refresh-on-profile-update, since it's the
  more common case.
- Replace the operations table with a link to the API reference.
- Drop the quickstart link, which has no target on this branch.
- Pricing: idle pooled browsers incur no usage charges, not "disk
  charges".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Polish the pools page after review

- Refer to on-demand browsers rather than browsers.create() in prose,
  and drop the size/fill-rate parameter mismatch: the code sample and
  API reference own parameter names and defaults, not the prose.
- Cut the fill-rate link from five places to one, in Sizing, where
  you'd act on it.
- Give flush its own short section under Update, where it's the remedy
  for stale configuration, and restore the two links that pointed at it.
- Say "browser pool" at each section's first mention, keeping "the pool"
  only for back-references; rename the Create, Update, and per-user
  headings to match, updating the links that referenced them.
- Remove three more restatements: the Create lead repeated the Steps
  block, the Update warning re-explained discard_all_idle, and the
  per-user lead repeated the read-only paragraph above it.
- Soften releasing into a best practice rather than an instruction, and
  trim the Managed Auth mention to a pointer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Open the pools page with a definition

The intro stated the same idea three times — configure once, get
pre-configured browsers — and never actually said what a browser pool
is. Replace it with three paragraphs doing one job each: what a browser
pool is, why acquiring is faster, and what it costs. The Chromium
restart becomes part of the start-up point rather than a third parallel
clause.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Tighten browser pools copy and fix update-size docs

- Drop the "size is always required on update" note: size is optional on
  update (required only on create), and following the note risks resizing
  the pool as a side effect of an unrelated config change.
- Fix the Go update sample, which passed a bare int for an optional field.
- Rework the sizing section: gloss available_count/acquired_count in prose,
  and match the page's bold-lead-in bullet pattern.
- Fold the one-line flush subsection into the update warning that already
  referenced it, and add flush to the API reference pointer.
- Drop the "pre-" from the page description.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Replace "the right tool" in the Scale intro

A browser pool and browsers.create() are two ways of provisioning the same
browser, not two instruments to pick between, so "the right tool" reads
oddly here. Use the verb the section below already uses.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Add pools/faq redirect and drop remaining reserved-browsers wording

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: andrewleesteele <8799863+andrewleesteele@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: andrewleesteele

auth/profiles.mdx

@@ -264,7 +264,7 @@ You cannot load a profile into a browser that was already created with a profile
 </Warning>
 
 <Note>
-To use profiles with browser pools, read: [Can pooled browsers save changes back to a profile?](/browsers/pools/faq#can-pooled-browsers-save-changes-back-to-a-profile)
+To use profiles with browser pools, see [Profiles with browser pools](/browsers/pools#profiles-with-browser-pools)
 </Note>
 
 ## Other ways to use profiles
@@ -494,5 +494,5 @@ _ = browser
 - Profiles store cookies and local storage. Start the session with `save_changes: true` to write changes back when the browser is closed.
 - To keep a profile immutable for a run, omit `save_changes` (default) when creating the browser.
 - Multiple browsers in parallel can use the same profile, but only one browser should write (`save_changes: true`) to it at a time. Parallel browsers with `save_changes: true` may cause profile corruption and unpredictable behavior.
-- `save_changes` applies to a profile attached to a single browser — either at creation (`kernel.browsers.create()`) or loaded afterward with `kernel.browsers.update()`. A profile set on a [browser pool's](/browsers/pools/overview) config is loaded read-only and never persisted; `save_changes` sent on a pool's profile is silently ignored. To persist per-user state through a pool, attach the profile after acquiring the browser and release with `reuse: false` — see [Per-user profiles with pools](/browsers/pools/overview#per-user-profiles-with-pools).
+- `save_changes` applies to a profile attached to a single browser — either at creation (`kernel.browsers.create()`) or loaded afterward with `kernel.browsers.update()`. A profile set on a [browser pool's](/browsers/pools) config is loaded read-only and never persisted; `save_changes` sent on a pool's profile is silently ignored. To persist per-user state through a pool, attach the profile after acquiring the browser and release with `reuse: false` — see [Per-user profiles with pools](/browsers/pools#per-user-profiles-with-browser-pools).
 - Profile data is encrypted end to end using a per-organization key.

browsers/bot-detection/overview.mdx

@@ -31,12 +31,12 @@ Every Kernel browser launches with anti-detection chrome configuration applied.
 On top of the defaults, stealth mode adds a default ISP proxy and an automatic CAPTCHA solver. Both are opt-out so you can BYO proxy and/or CAPTCHA tooling.
 
 ### [Configurable Proxies](/proxies/overview)
-Bring your own proxy network or use Kernel's managed pool (selectable down to ZIP-code level). If needed, use the same IP to reduce detection and allow for regional testing or QA.
+Bring your own proxy network or use Kernel's managed proxy pool (selectable down to ZIP-code level). If needed, use the same IP to reduce detection and allow for regional testing or QA.
 
 ### [Profiles](/auth/profiles)
 Profiles persist cookies, local storage, and session data between runs. Combined with a fixed proxy, this mimics a returning user. We recommend using them to persist authenticated states and reduce CAPTCHAs.
 
-### [Browser Pools](/browsers/pools/overview)
+### [Browser Pools](/browsers/pools)
 Browser pools let you reuse browsers across multiple visits to the same website, which introduces consistency with respect to the IP address. Since IP addresses are one of the main components of fingerprinting used by modern bot detection systems, browser pools drastically increase your chances of avoiding detection.
 
 ### [Playwright Execution API](/browsers/playwright-execution)
@@ -92,7 +92,7 @@ Kernel's [stealth mode](/browsers/bot-detection/stealth) uses static ISP proxies
 
 [Residential proxies](/proxies/residential) route traffic through real consumer devices, making them the least detectable proxy type by ASN classification. However, exit IPs [rotate per connection](/proxies/residential#ip-rotation-behavior) since the underlying devices come online and offline dynamically — different tabs hitting different domains will likely show different public IPs.
 
-Some IP-reputation-based detection systems (such as reCAPTCHA) can detect rotating pool traffic patterns and penalize them, regardless of how clean the individual exit IPs are. On the other hand, residential proxies tend to be a stronger choice against fingerprint-heavy vendors where detection focuses on the browser and behavioral layer rather than the network layer. Residential proxies also offer richer geo-targeting (country, state, city, ZIP, ASN) compared to ISP.
+Some IP-reputation-based detection systems (such as reCAPTCHA) can detect rotating proxy-pool traffic patterns and penalize them, regardless of how clean the individual exit IPs are. On the other hand, residential proxies tend to be a stronger choice against fingerprint-heavy vendors where detection focuses on the browser and behavioral layer rather than the network layer. Residential proxies also offer richer geo-targeting (country, state, city, ZIP, ASN) compared to ISP.
 
 ### Datacenter proxies
 

browsers/chrome-policies.mdx

@@ -9,7 +9,7 @@ Keys are Chrome policy names and values are the corresponding settings. The same
 
 ## Setting chrome policies on a pool
 
-Pass a `chrome_policy` object when [creating](/browsers/pools/overview#create-a-pool-of-reserved-browsers) or [updating](/browsers/pools/overview#update-a-pool) a pool.
+Pass a `chrome_policy` object when [creating](/browsers/pools#create-a-browser-pool) or [updating](/browsers/pools#update-a-browser-pool) a pool.
 
 <CodeGroup>
 ```typescript Typescript/Javascript

browsers/curl.mdx

@@ -157,9 +157,9 @@ func main() {
 
 Browser curl concurrency is constrained by Chromium's internal networking limits:
 
-- **HTTP/1.x (direct)** — About 6 sockets per host group and up to 256 active sockets per pool.
+- **HTTP/1.x (direct)** — About 6 sockets per host group and up to 256 active sockets per connection pool.
 - **Proxied chains** — On the order of tens of sockets per proxy chain (Chromium clamps configured values into a bounded range).
 - **HTTP stream pool** — Similar per-group and per-pool behavior to HTTP/1.x direct connections.
 - **HTTP/2** — Roughly 100 concurrent streams per session initially, updated from the server's `SETTINGS_MAX_CONCURRENT_STREAMS`, with an upper cap in Chromium (on the order of 256).
 
-If you're issuing many parallel curls from one browser, you're sharing those pools with navigation, XHR, and other session traffic. Latency may vary, as Chromium may queue requests when it reaches its limits.
+If you're issuing many parallel curls from one browser, you're sharing those connection pools with navigation, XHR, and other session traffic. Latency may vary, as Chromium may queue requests when it reaches its limits.

browsers/extensions.mdx

@@ -52,7 +52,7 @@ The response includes the extension's ID, name, size, and timestamps.
 Passing the extension name or ID to the `create` method will load it into the browser.
 
 <Info>
-    Loading an extension into a browser triggers a Chromium restart, which can take several seconds. Use [browser pools](/browsers/pools/overview) to access browsers with extensions faster.
+    Loading an extension into a browser triggers a Chromium restart, which can take several seconds. Use [browser pools](/browsers/pools) to access browsers with extensions faster.
 </Info>
 
 

browsers/live-view.mdx

@@ -88,7 +88,7 @@ connect-src https://*.onkernel.com:8443
 Kiosk mode provides a fullscreen live view experience without browser UI elements like the address bar and tabs. You can enable kiosk mode when creating a browser by setting the `kiosk_mode` parameter to `true`.
 
 <Info>
-    Kiosk mode triggers a Chromium restart, which can take several seconds. Use [browser pools](/browsers/pools/overview) to access kiosk mode browsers faster.
+    Kiosk mode triggers a Chromium restart, which can take several seconds. Use [browser pools](/browsers/pools) to access kiosk mode browsers faster.
 </Info>
 
 <CodeGroup>

browsers/performance.mdx

@@ -11,7 +11,7 @@ Kernel browsers [benchmark](https://www.kernel.sh/benchmarks) as the fastest, mo
 | P99 | 105ms | April 24, 2026 |
 
 ### Troubleshooting latency
-If you're experiencing slower-than-expected browser creation (or [browser pool acquisition](/browsers/pools/overview)), review your configuration for the following:
+If you're experiencing slower-than-expected browser creation (or [browser pool acquisition](/browsers/pools)), review your configuration for the following:
 
 1. App code ⇔ Kernel browser region
 
@@ -23,11 +23,11 @@ Kernel enforces [rate limits](/info/pricing#rate-limiting) on browser creation b
 
 3. Non-default browser configurations
 
-Certain browser configurations trigger Chromium to restart, which can take several seconds. Use [browser pools](/browsers/pools/overview) to access browsers with custom configurations faster. The following configurations cause browser restarts, as well as disrupt active CDP connections:
+Certain browser configurations trigger Chromium to restart, which can take several seconds. Use [browser pools](/browsers/pools) to access browsers with custom configurations faster. The following configurations cause browser restarts, as well as disrupt active CDP connections:
 - Custom viewport configurations
 - Chrome extensions
 - Setting the live view to `kiosk mode`
 
 4. Browser pool refill rate
 
-Browser pools fill at a [specified rate](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute). Read about browser pool lifecycle best practices [here](/browsers/pools/overview#how-browser-pools-work).
+Browser pools fill at a [specified rate](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute). Read about browser pool lifecycle best practices [here](/browsers/pools#how-browser-pools-work).