add guidance on bpools

[juecd]

Adds guidance on bpool behavior and best practices for using them. Also adds page about troubleshooting latency

---

Note

Low Risk
Low risk documentation-only changes; main risk is minor navigation/linking or content accuracy issues.

Overview
Adds a new browsers/performance page documenting browser creation latency benchmarks and common latency troubleshooting steps (region placement, rate limits, non-default configs, and pool refill rate).

Expands browsers/pools/overview with a How browser pools work walkthrough covering pool declaration vs acquisition, fixed pool capacity, and the importance of releasing browsers.

Updates navigation (docs.json) to include the new performance FAQ page and adds a new reserved-browsers doc entry (browsers/pools/policy-json), with a corresponding changelog note.

^{Reviewed by Cursor Bugbot for commit 5b2264b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Kernel	🔴 Failed	–	Apr 24, 2026, 6:03 PM

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

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR adds documentation/guidance on bpools with no changes to API endpoints or Temporal workflows.

To monitor this PR anyway, reply with @firetiger monitor this.

[cursor]

Risk assessment: Very Low.

I reviewed the actual diff and this PR is documentation/navigation only:

• Added explanatory content to browsers/pools/overview.mdx
• Renamed browsers/pools/managing-browsers.mdx to browsers/pools/policy-json.mdx with no content change (R100)
• Updated links in changelog.mdx and docs.json

No application runtime logic, shared services, infrastructure, auth, permissions, or production code paths are modified. Blast radius is limited to docs content and sidebar routing, so this is safe to approve.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2446bb7. Configure here.}

[cursor]

API reference links use inconsistent www. subdomain

Low Severity

The two new /api-reference/ links use https://www.kernel.sh/docs/api-reference/... instead of the prescribed format https://kernel.sh/docs/api-reference/.... The rest of the same file (and codebase) consistently uses the non-www. form. The www. variant may not be recognized as an external link by the mint broken-links CI checker, potentially causing build failures.

Additional Locations (1)

• browsers/pools/overview.mdx#L16-L17

 

^{Triggered by learned rule: Use absolute URLs for /api-reference/ links}

^{Reviewed by Cursor Bugbot for commit 2446bb7. Configure here.}

[cursor]

Risk assessment for current PR state: Very Low.

I re-evaluated the actual diff at 05cabc90ee48c12ad103a9d5e9efe5ea3eeb7d3a...1adb4acd96e70ccc9ac474a7f2dd4d2a0cd67070:

• Added documentation content in browsers/pools/overview.mdx
• Renamed browsers/pools/managing-browsers.mdx to browsers/pools/policy-json.mdx with no content change
• Updated references in changelog.mdx and docs.json

No runtime application logic, auth/permissions, infrastructure, or production service codepaths were modified. Blast radius is limited to docs content/navigation.

This PR is already approved, so I did not add another approval.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk assessment for current PR state: Very Low.

I re-evaluated the latest diff (05cabc90ee48c12ad103a9d5e9efe5ea3eeb7d3a...3fc7cb13babe9c22f5f8be9d3e4a4d18d82622ad) based on changed files and codepaths:

• Added docs page: browsers/performance.mdx
• Expanded docs content: browsers/pools/overview.mdx
• Renamed docs page with no content change: browsers/pools/managing-browsers.mdx -> browsers/pools/policy-json.mdx
• Updated docs references/navigation: changelog.mdx, docs.json

No runtime application logic, auth/permissions paths, shared service code, or infrastructure behavior is modified. Blast radius is limited to documentation content and site navigation.

This PR is already approved, so I did not add another approval.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk assessment for the current PR state: Very Low.

I reviewed the actual diff at 05cabc90ee48c12ad103a9d5e9efe5ea3eeb7d3a...5b2264b3b19944d4ae1a7b03c9acf4dc654c5edb:

• Added docs content: browsers/performance.mdx
• Expanded docs guidance: browsers/pools/overview.mdx
• Pure rename with no content change (R100): browsers/pools/managing-browsers.mdx -> browsers/pools/policy-json.mdx
• Updated docs links/navigation: changelog.mdx, docs.json

No runtime codepaths, auth/permissions logic, infrastructure, or production service behavior changed. Blast radius is limited to documentation content and docs site navigation.

This PR already has an approval, so I did not add another approval.

  

_{Sent by Cursor Automation: Assign PR reviewers}