Fix inverted discard_all_idle default in pool docs

[masnwilliams]

Summary

Corrects the discard_all_idle default across the browser-pools docs. The API default is false — a plain update() leaves existing idle browsers on their original config and only newly created browsers pick up the change. The docs stated the inverse (discards-idle-by-default), which was merged in #431 and also predated it.

Source of truth confirming default = false:

• Handler packages/api/cmd/api/api/browser_pools.go only flushes if DiscardAllIdle != nil && *DiscardAllIdle — omitted means no rebuild.
• Generated oapi.go: DiscardAllIdle *bool (omitempty).
• Dashboard edit-pool-dialog.tsx: checkbox defaults to false.
• OpenAPI spec: discard_all_idle has default: false (kernel/kernel#2591 keeps this correct).

Changes

• browsers/pools/overview.mdx — "Update a pool" intro, the discard_all_idle paragraph, and the <Warning> parenthetical: flip to keep-idle-by-default; pass discard_all_idle: true (or flush()) to rebuild idle browsers.
• browsers/pools/faq.mdx — "Can I update a pool's configuration…", "…do browsers currently in use pick up the new configuration?", and "Can I use different browser configurations…": same correction, and clarify that a plain update() rebuilds nothing already-warm.

Open question

This assumes keep-idle-by-default is intended (code, spec, and dashboard all agree). If the product intent was discard-by-default, this is instead a code/spec bug and the fix belongs there — flagging for a quick confirm before merge.

Test plan

• Mintlify preview renders both pages; <Warning> and the flush() anchor resolve.

---

Note

Low Risk
Documentation-only changes with no runtime or API behavior impact.

Overview
Fixes browser pool documentation that incorrectly described discard_all_idle as discarding idle browsers by default on update().

browsers/pools/overview.mdx and browsers/pools/faq.mdx now state the API default is discard_all_idle: false: a plain kernel.browserPools.update() leaves existing idle browsers on their original config and only applies the new configuration to browsers created afterward. discard_all_idle: true or flush() is documented as the way to rebuild idle browsers immediately.

Related FAQ and warning copy is updated so it no longer claims idle browsers are rebuilt by default, and it clarifies that in-use browsers are never rebuilt during an update regardless of the flag.

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

[cursor]

Risk assessment: Very Low

This PR changes only two MDX documentation pages under browsers/pools/, with a small 6-addition/6-deletion diff clarifying the documented default behavior for discard_all_idle. I found no code, configuration, navigation, prompt, infrastructure, auth, billing, permissions, or schema changes, and no CODEOWNERS file in the workspace requiring owner review.

Approved because the blast radius is limited to docs content and the risk is Very Low.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Jul 2, 2026, 4:28 PM

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