add guidance on bpools

Author: juecd

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.

browsers/pools/managing-browsers.mdx browsers/pools/policy-json.mdxbrowsers/pools/managing-browsers.mdx renamed to browsers/pools/policy-json.mdx

@@ -56,7 +56,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>

changelog.mdx

@@ -140,7 +140,7 @@
                     "group": "Reserved Browsers",
                     "pages": [
                       "browsers/pools/overview",
-                      "browsers/pools/managing-browsers",
+                      "browsers/pools/policy-json",
                       "browsers/pools/scaling",
                       "browsers/pools/faq"
                     ]