add guidance on bpools

browsers/performance.mdx

@@ -0,0 +1,33 @@
+---
+title: "Performance"
+---
+
+Kernel browsers [benchmark](https://www.kernel.sh/benchmarks) as the fastest, most performant browsers in the market.
+
+### Kernel browser creation latency
+| Benchmark | Latency | Last reported |
+|-----------|---------|---------------|
+| P50 | 30ms | April 24, 2026 |
+| 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:
+
+1. App code ⇔ Kernel browser region
+
+Kernel browsers run in `us-east`. Use our [app platform](/apps/develop) to colocate your browser agent or automation.
+
+2. Create browser rate limit
+
+Kernel enforces [rate limits](/info/pricing#rate-limiting) on browser creation based on your plan. Our SDKs automatically retry, respecting the `Retry-After` header for delay timing. If retries are exhausted, the SDK throws a typed `RateLimitError` with the response headers accessible for custom backoff logic.
+
+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:
+- 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).

browsers/pools/overview.mdx

@@ -5,6 +5,27 @@ description: "Pre-configure pools of reserved browsers for immediate acquisition
 
 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, allowing you to minimize browser start-up latency and scale your workloads in production.
 
+## How browser pools work
+
+Browser pools are a way to pre-configure a fixed set of browsers without being charged for them until they are used (i.e. `acquired`). All browsers in the pool share the same settings upon instantiation.
+
+<Steps>
+  <Step title="Declare a pool">
+    First, declare a pool of browsers with your specified configuration. The pool takes time to fill (see [fill rate per minute](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute)), so declare your pool outside your browser automation / agent runtime logic. Pool declarations should be decoupled from browser use logic for the best performance.
+  </Step>
+  <Step title="Acquire a browser">
+    You can acquire a browser as soon as you've created a pool. The request returns immediately if a browser is available, or waits until one becomes available. The `acquire_timeout_seconds` parameter controls how long to wait for a browser; it defaults to the calculated time it would take to fill the pool at the pool's configured [fill rate](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute).
+
+    The total number of usable browsers is fixed to the `size` specified upon browser pool creation.
+
+    When you acquire a browser, the pool's available count is decremented by one. When you release a browser, the pool's available count is incremented by one. put differently, the pool does not top up when you acquire a browser: browsers are "borrowed" from the pool and must be returned when you're done with them, either by [releasing them](#release-a-browser) or allowing them to [timeout](#timeout-behavior).
+  </Step>
+  <Step title="Release a browser">
+    When you're done with a browser, release it back to the pool. this step is important; otherwise, the browser will continue to be in an `acquired` state until it [times out](#timeout-behavior). Failing to release browsers may result in unexpected latency when acquiring future browsers if the pool is only refilling when browsers timeout.
+  </Step>
+</Steps>
+
+
 ## Create a pool of reserved browsers
 
 Create a browser pool with a specified size and configuration. All browsers in the pool share the same settings.

changelog.mdx

@@ -57,7 +57,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
 ## Documentation updates
 
 - Documented MFA token auto-retry behavior for [managed auth](/auth/overview) sessions.
-- Added a new [Managing Browsers](/browsers/pools/managing-browsers) page to the Reserved Browsers documentation.
+- Added a new [policy.json](/browsers/pools/policy-json) page to the Reserved Browsers documentation.
 - Clarified that [profiles](/auth/profiles) can have multiple auth connections.
 - Added a Headful + GPU acceleration option to the [pricing calculator](/info/pricing#pricing-calculator).
 </Update>

docs.json

@@ -140,12 +140,18 @@
                     "group": "Reserved Browsers",
                     "pages": [
                       "browsers/pools/overview",
-                      "browsers/pools/managing-browsers",
+                      "browsers/pools/policy-json",
                       "browsers/pools/scaling",
                       "browsers/pools/faq"
                     ]
                   }
                 ]
+              },
+              {
+                "group": "FAQ",
+                "pages": [
+                  "browsers/performance"
+                ]
               }
             ]
           },