Refresh browser pool guides and standardize on "browser pools"

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 [Per-user profiles with pools](/browsers/pools/overview#per-user-profiles-with-pools)
 </Note>
 
 ## Other ways to use profiles

browsers/pools/overview.mdx

@@ -1,11 +1,13 @@
 ---
 title: "Overview"
-description: "Pre-configure pools of reserved browsers"
+description: "Pre-configure pools of warm, ready-to-use browsers"
 ---
 
-Browser pools let you maintain a set of reserved, identical browsers ready for immediate use. Use them to set your preferred browser configuration in advance (such as stealth, proxies, extensions, and profiles), allowing you to minimize browser start-up latency and scale your workloads in production. 
+Browser pools let you maintain a set of identically-configured browsers ready for immediate use. Use them to set your preferred browser configuration in advance (such as stealth, proxies, extensions, and profiles), allowing you to minimize browser start-up latency and scale your workloads in production.
 
-Acquiring a browser from a pool is faster than creating a browser directly. Reserved browsers and on-demand browsers share the same concurrency limit, and reserved browsers aren't billed until they're used. See [Scale](/introduction/scale) for how pools fit into best practices for production architecture.
+Acquiring a browser from a pool is faster than creating a browser directly. Pooled browsers and on-demand browsers share the same concurrency limit, and browsers sitting idle in a pool aren't billed until they're used. See [Scale](/introduction/scale) for how pools fit into best practices for production architecture.
+
+Two things make acquisition faster than `browsers.create()`. The browser is already booted with your configuration applied — including [configurations that restart Chromium](/browsers/performance#troubleshooting-latency) when applied to a fresh browser, such as custom viewports, extensions, and kiosk-mode live view. And acquiring from a pool isn't subject to the [rate limit](/info/pricing#rate-limiting) on browser creation that high-volume workloads otherwise hit.
 
 ## How browser pools work
 
@@ -38,7 +40,7 @@ Browser pools are a way to pre-configure a fixed set of browsers without being c
 </Steps>
 
 
-## Create a pool of reserved browsers
+## Create a pool
 
 Create a browser pool with a specified size and configuration. All browsers in the pool share the same settings.
 
@@ -125,7 +127,7 @@ func main() {
 
 Pools can be pre-configured with options like start url, custom extensions, supported viewports, residential proxies, profiles, and more. See the [API reference](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool) for more details.
 
-A profile attached to a pool is loaded read-only: pooled browsers never persist changes back to the profile, so `save_changes` does not apply to pools (it is silently ignored if sent). To capture profile state, use a single browser session with `save_changes` instead — see [Profiles](/auth/profiles).
+A profile attached to a pool is loaded read-only: pooled browsers never persist changes back to the profile, so `save_changes` does not apply to pools (it is silently ignored if sent). This doesn't block per-user persistence — to load and save per-user profiles through a pool's warm browsers, attach the profile *after* you acquire, following [Per-user profiles with pools](#per-user-profiles-with-pools). For a standalone session, use [Profiles](/auth/profiles) with `save_changes`.
 
 When a pool has a profile attached, `refresh_on_profile_update` is automatically enabled — the pool flushes idle browsers whenever the profile's contents are updated, so it always picks up the latest profile data. See [Refresh on profile update](#refresh-on-profile-update) below.
 
@@ -176,6 +178,15 @@ Browsers remain in the pool indefinitely until acquired. Once acquired, the pool
 
 When you're done with a browser, release it back to the pool. By default, the browser instance is reused. Set `reuse: false` to destroy it and create a fresh one.
 
+Reuse controls whether browser state carries across acquisitions:
+
+- **`reuse: true`** (default) returns the same browser instance to the pool without resetting it. Cookies, local storage, logged-in sessions, and open tabs persist, and the next caller to acquire it inherits that state. Fast, but not isolated between acquirers.
+- **`reuse: false`** destroys the browser and refills the pool with a fresh one. Isolated and clean, at the cost of a rebuild at the pool's [fill rate](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute).
+
+<Warning>
+If you acquire pooled browsers on behalf of different end users, releasing with `reuse: true` leaks one user's session to the next. Use `reuse: false` for per-user work — see [Per-user profiles with pools](#per-user-profiles-with-pools).
+</Warning>
+
 <CodeGroup>
 ```typescript Typescript/Javascript
 await kernel.browserPools.release("my-pool", {
@@ -268,7 +279,7 @@ You have three ways to get an in-use browser onto the new configuration:
 
 ## Per-user profiles with pools
 
-A profile attached to the pool config is [read-only](#create-a-pool-of-reserved-browsers) and shared by every browser, so it can't hold per-user login state across many users in a single pool. To use a pool's pre-warmed browsers to load many different per-user profiles **and** persist each user's state, attach the profile to the browser *after* you acquire it, then destroy the browser on release:
+A profile attached to the pool config is [read-only](#create-a-pool) and shared by every browser, so it can't hold per-user login state across many users in a single pool. To use a pool's pre-warmed browsers to load many different per-user profiles **and** persist each user's state, attach the profile to the browser *after* you acquire it, then destroy the browser on release:
 
 1. **Create the pool with no profile.** A profile can only be loaded into a browser that was created without one, so the pool must be profile-free.
 2. **Acquire a browser** from the pool.
@@ -472,6 +483,16 @@ if err := client.BrowserPools.Delete(ctx, "my-pool", kernel.BrowserPoolDeletePar
 ```
 </CodeGroup>
 
+## Sizing a browser pool
+
+`retrieve` returns `available_count` (browsers ready to acquire right now) and `acquired_count` (browsers in use). Watch `available_count` to size the pool:
+
+- If it regularly hits **0**, tasks are queueing behind `acquire` — the pool is too small.
+- If it stays above **30–40%** of the pool size under normal load, you're over-provisioned and can shrink the pool to free up concurrency.
+- Target **10–20%** available during typical load.
+
+Resize at any time with `update` — no need to tear the pool down and rebuild it. Added capacity warms up at the pool's [fill rate](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute), so raise the size before a traffic peak rather than during it. As a rough starting point, a browser pool earns its keep once you're running many browsers concurrently (roughly 50+); below that, on-demand `browsers.create()` is usually enough.
+
 ## Full example
 
 This example assumes you've already created a pool named "my-pool". In practice, you'd create pools once (via the SDK, CLI, or dashboard) and then acquire from them repeatedly.

browsers/pools/policy-json.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Custom Chrome Policies"
-description: "Customize Chrome behavior in reserved browser pools using Chrome policies"
+description: "Customize Chrome behavior in browser pools using Chrome policies"
 ---
 
 Browser pools accept an optional [`chrome_policy`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) object that lets you apply [Chrome enterprise policies](https://chromeenterprise.google/policies/) to every browser in the pool. Use this to control startup behavior, default homepages, bookmarks, and other browser-level settings.
 
 ## Setting chrome policies
 
-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. Keys are Chrome policy names and values are the corresponding settings.
+Pass a `chrome_policy` object when [creating](/browsers/pools/overview#create-a-pool) or [updating](/browsers/pools/overview#update-a-pool) a pool. Keys are Chrome policy names and values are the corresponding settings.
 
 <CodeGroup>
 ```typescript Typescript/Javascript
@@ -176,7 +176,7 @@ The example above demonstrates setting a default homepage and managed bookmarks.
 
 ## Common use cases
 
-`chrome_policy` is also accepted directly on `browsers.create()` when you don't need a reserved pool. The examples below use that path.
+`chrome_policy` is also accepted directly on `browsers.create()` when you don't need a pool. The examples below use that path.
 
 ### Allow pop-ups
 

docs.json

@@ -162,11 +162,10 @@
                     ]
                   },
                   {
-                    "group": "Reserved Browsers",
+                    "group": "Browser Pools",
                     "pages": [
                       "browsers/pools/overview",
-                      "browsers/pools/policy-json",
-                      "browsers/pools/faq"
+                      "browsers/pools/policy-json"
                     ]
                   }
                 ]

index.mdx

@@ -75,4 +75,4 @@ kernel invoke my-agent my-task --payload '{"url": "https://example.com"}'
 
 ### scaling 
 
-once you're ready to scale, check out how to create a [pool of reserved browsers](/browsers/pools/overview).
+[browser pools](/browsers/pools/overview) are how you take a working automation to production: they keep browsers warm and pre-configured so you skip start-up latency on every task, and idle browsers in a pool aren't billed. once you know how to create and drive a browser, browser pools are worth evaluating for almost any production workload.

info/concepts.mdx

@@ -5,6 +5,8 @@ title: "Concepts"
 ## Browser
 A `Browser` is a cloud-based browser managed by Kernel. They accept Chrome DevTools Protocol connections and can be used to run browser automations or web agents.
 
+## Browser Pool
+A `Browser Pool` is a set of identically-configured browsers that Kernel keeps warm and ready to use. You acquire a browser from the pool when a task starts and release it back when the task finishes. Browser pools remove browser start-up latency from your workload — see [Browser Pools](/browsers/pools/overview).
 
 ## App
 An `App` is a codebase deployed on Kernel. You can use Kernel for a variety of use cases, including web automations, data processing, and more.

info/pricing.mdx

@@ -45,9 +45,9 @@ import { PricingCalculator } from '/snippets/calculator.jsx';
 
 > Note: Included monthly credits apply to usage costs only.
 
-## Reserved browsers (browser pools)
+## Browser pools
 
-With Browser Pools, you pay the standard usage-based price per GB-second while browsers are running. Idle browsers in a pool incur no disk charges — you only pay when a browser is actively in use.
+With [browser pools](/browsers/pools/overview), you pay the standard usage-based price per GB-second while browsers are running. Idle browsers in a pool incur no disk charges — you only pay when a browser is actively in use, so keeping a pool warm between tasks costs nothing.
 
 > Note: GPU acceleration is not available for browser pools.
 
@@ -59,7 +59,7 @@ Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session he
 
 ## Concurrency limits
 
-Kernel enforces a single concurrency limit covering all browsers you run at once — whether created on demand with `browsers.create()` or reserved in a [browser pool](/browsers/pools/overview). Your full limit is available to either API in any mix.
+Kernel enforces a single concurrency limit covering all browsers you run at once — whether created on demand with `browsers.create()` or warmed in a [browser pool](/browsers/pools/overview). Your full limit is available to either API in any mix.
 
 | Feature | Developer (free + usage) | Hobbyist ($30 / mo + usage) | Start-Up ($200 / mo + usage) | Enterprise |
 | --- | --- | --- | --- | --- |
@@ -68,7 +68,7 @@ Kernel enforces a single concurrency limit covering all browsers you run at once
 | App invocations (per-app) | 5 | 10 | 20 | Custom |
 | Managed auth health check interval | N/A | 1 hour minimum | 20 minutes minimum | Custom |
 
-> Note: Reserved capacity in a [browser pool](/browsers/pools/overview) counts toward your concurrency limit whether or not the browsers are currently acquired — a pool sized to 40 browsers uses 40 of your limit. Browser pools are available on Start-Up and Enterprise plans.
+> Note: A [browser pool](/browsers/pools/overview) counts toward your concurrency limit whether or not its browsers are currently acquired — a pool sized to 40 browsers uses 40 of your limit. Browser pools are available on Start-Up and Enterprise plans.
 
 > Note: Browsers in [Standby Mode](/browsers/standby) count against your concurrency limit.