You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Browser pools weren't surfaced where a user decides to go to production — the concept was called "Reserved Browsers" in the sidebar, and the Create page never mentioned them. And the pools page itself had grown into a tutorial and an API reference wearing one hat, explaining the same handful of facts three and four times over.
This PR is scoped to browser pools documentation. The end-to-end quickstart is #470 (stacked on this branch), and the broader docs IA rework — replacing Basics/Intermediate/Advanced with lifecycle groups — is tracked separately. (Merged main to pick up #469, which moved Chrome policies to a standalone page.)
1. One name: "browser pools", and every other "pool" qualified. The API, SDKs, CLI, and dashboard already said "browser pools" — the docs were the outlier. Renamed the sidebar group, dropped "reserved browsers" as a product name, and swept bare "pool" → "browser pool" in prose. "Pool" is overloaded here, so the other senses are disambiguated too: "connection pool" on the curl networking limits, "managed proxy pool" on bot-detection. ("ISP pool" and the unikernels page's "warm pools" were already unambiguous.)
2. Not described as "warm". Per docs-team feedback on this PR, "warm" implies pools run hot and bill for idle time — the opposite of the actual benefit. Now "ready to use" / "pre-provisioned", and the pricing line leads with the benefit: "an idle browser pool costs nothing between tasks."
3. One page at /browsers/pools. The section was three pages (overview + FAQ + Chrome policies); it's now one, served at /browsers/pools rather than /browsers/pools/overview. The FAQ folded in, Chrome policies left via #469, the nav group collapsed to a single entry, and a redirect covers the old path. The changelog's bare /browsers/pools links — previously 404s — now resolve, because that's where the page actually lives.
4. Deduped. The intro explained "config is pre-applied so acquisition is faster" four times; read-only profiles appeared three times; update/stale-config semantics three times, including a paragraph duplicated verbatim two paragraphs later; refresh_on_profile_updatethree times. Merged the three profile sections into one "Profiles with browser pools", moved the stale-config warning to "Update a pool" where it belongs, replaced "Pool configuration options" with a short Configuration pointer, and moved Sizing next to the acquire/release lifecycle.
5. Pitched where users move to production, workload-driven. An "On demand or from a browser pool" section on introduction/create (build with browsers.create(), move to a pool once you're repeating the same task), plus pointers from the home page and Scale. Fundamentals first, then pools — not a day-one default, not an afterthought.
6. Scale page rewritten. It was written pre-launch and framed pools around three co-equal factors with a blunt "<50 concurrency → don't bother" gate. Now: benefit (low-latency acquisition, reserved capacity, higher creation throughput; the concurrency-limit tradeoff) → when to use vs on-demand (workload signals, not thresholds) → sizing (links to the pools page), keeping the three architecture patterns and dropping their numeric gates.
7. Content gaps closed.
Reuse semantics — reuse: true (default) returns the same browser with cookies/storage/sessions intact, so it's fast but not isolated; reuse: false is clean at the cost of a rebuild. Multi-tenant leak warning added.
Why acquiring is faster — pre-applied restart-triggering configs, and no browser-creation rate limit.
Read-only profiles — point to the per-user-profiles pattern instead of "use a standalone session," which undersold it.
Sizing — watch available_count, target 10–20% available; a small pool still pays off when acquisition latency matters, with no concurrency-number gate.
Limitations — new section: no GPU browsers, one fixed config per pool (start_url the only per-acquire override), read-only profiles, reserved capacity holds concurrency slots whether or not acquired, Start-Up/Enterprise only.
fill_rate_per_minute example aligned with the documented 25% default (was 10, which read as a competing default).
Verification
Merged origin/main; resolved docs.json and took main's canonical browsers/chrome-policies.mdx.
docs.json valid; every nav page resolves to a file; the pools entry is a single browsers/pools page; no stale overview/faq/policy-json nav refs.
All internal /browsers/pools/overview links repointed; a stale #create-a-pool-of-reserved-browsers anchor fixed; every in-page anchor resolves; externally-linked anchors preserved (#how-browser-pools-work, #create-a-pool, #update-a-pool, #sizing-a-browser-pool, #per-user-profiles-with-pools).
API details verified against the OpenAPI spec — 25% default fill rate, 600s default timeout, size required on update. "Acquire isn't rate-limited" verified against the API's rate-limiter: only POST /browsers is rate-limited.
mint dev not booted in this environment, so the pages aren't visually confirmed. Worth a preview pass before merge.
Add a Browser Pools Quickstart, move the pool guides from Advanced to
Basics, and use "browser pools" as the single name for the concept
everywhere in the docs (the API, SDKs, CLI, and dashboard already do).
Push pools as the production path from the Create page, the home page,
and the Scale guide, and lead with the fact that idle pooled browsers
aren't billed.
- Document that reuse: true persists browser state across acquisitions
(not isolated) and reuse: false is the clean/per-user path, with a
multi-tenant leak warning.
- Explain why acquiring is faster than browsers.create(): pre-applied
restart-triggering configs and no create-endpoint rate limit.
- Point the read-only-profile note at the per-user-profiles pattern
instead of a standalone session.
- Fold two update-semantics FAQ entries into one pointer to the
canonical Update a pool section; align the fill-rate example with the
25% default.
- Keep the Browser Pools nav group in Advanced for now.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The pools quickstart is being folded into a future unified Kernel
quickstart rather than living as a feature-specific guide. Delete the
page and its nav entry, and repoint the six inbound links
(home, pricing, concepts, create, scale, and the overview callout) to
the browser pools overview.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is 0ca62af, which removes browsers/pools/quickstart.mdx, drops its docs.json nav entry, and retargets intro/home links to the overview. That narrows scope; it does not raise risk.
Evidence (from full diff vs base)
10 files, all Mintlify docs: .mdx content plus a docs.json nav label rename (Reserved Browsers → Browser Pools).
Content/terminology updates and example code blocks on pools overview, FAQ, create, scale, pricing, concepts, and related pages.
No application code, APIs, auth, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Position browser pools as the step you reach when taking a working
automation to production, after learning to create and drive a browser
— rather than "most production workloads run on them from day one,"
which pushes them before the fundamentals.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is ad048aa. Since that approval, the branch removed the browser-pools quickstart (already assessed) and made a one-line home-page copy reframe in index.mdx. That does not raise risk.
Evidence (from full diff vs base)
10 files, all Mintlify docs: .mdx content plus a docs.json nav label rename (Reserved Browsers → Browser Pools).
Terminology, guidance, and example code-block updates across pools overview/FAQ, create, scale, pricing, concepts, and related pages.
No application code, APIs, auth, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Move the one piece of guidance the overview lacked — pool sizing via
available_count — into a Sizing section, and drop the FAQ page. Its
other entries duplicated overview sections (update, reuse, timeout,
profiles) or belonged elsewhere (target-site rate limiting, debugging).
Repoint the auth/profiles link to the per-user-profiles section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is 8f38449. Since that approval, the branch removed the browser-pools quickstart, reframed home-page copy, folded the FAQ into the overview (deleted browsers/pools/faq.mdx), added a short sizing section, and retargeted a profiles link. That does not raise risk.
Evidence (from full diff vs base)
11 files, all Mintlify docs: .mdx content plus docs.json nav updates (Reserved Browsers → Browser Pools; FAQ page removed from nav).
Terminology, guidance, and example code-block updates across pools overview, create, scale, pricing, concepts, and related pages.
No application code, APIs, auth, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Apply the naming rule to cross-page references (home, pricing, projects,
scale, create, proxies, reference, integrations) and the pools overview
intro so the feature is never shortened to "pool" — which collides with
connection pools, IP pools, and socket pools elsewhere in the docs.
Non-browser-pool uses (curl connection/socket pools, proxy IP/ISP pools)
are intentionally left for their own qualifiers.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is fd9c595. Since that approval, the branch removed the browser-pools quickstart, folded/deleted the FAQ, reframed home-page copy, and (latest) spell-out terminology updates replacing bare "pool" with "browser pool" across docs. That does not raise risk.
Evidence (from full diff vs base)
16 files, all Mintlify docs: .mdx content plus docs.json nav updates (Reserved Browsers → Browser Pools; FAQ page removed from nav).
Terminology, guidance, and example code-block updates across pools overview, create, scale, pricing, concepts, and related pages; FAQ deleted.
No application code, APIs, auth, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
With the FAQ folded in and Chrome policies moved out (#469), the
section is one page. Move browsers/pools/overview.mdx →
browsers/pools.mdx so it serves at /browsers/pools, retitle it
"Browser Pools", and collapse the nav group to a single entry.
Repoint every /browsers/pools/overview link to /browsers/pools, fix a
stale #create-a-pool-of-reserved-browsers anchor, and add a redirect
from the old overview path. Changelog's bare /browsers/pools links now
resolve to a real page.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is 59fcb57. Since that approval, the branch continued documentation-only work (FAQ fold/delete, terminology standardization, page collapse to /browsers/pools, Scale-page rewrite, pools-page dedupe). Latest delta (6b87a04 → 59fcb57) updates one cross-link in auth/profiles.mdx to point at #profiles-with-browser-pools. That does not raise risk.
Evidence (from full diff vs base)
25 files, all Mintlify docs: .mdx content plus docs.json nav/redirect updates (Reserved Browsers → single browsers/pools entry; FAQ removed; /browsers/pools/overview → /browsers/pools).
Net change about +178 / −189: terminology, guidance, example code blocks, page rename/dedupe, and related cross-links across pools, create, scale, pricing, concepts, and references.
Latest delta: 1 file, docs link only (+1 / −1).
No application code, APIs, auth logic, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Listing profiles alongside stealth, proxies, and viewport implied they
behave the same way. A pool takes one profile, shared read-only, so call
that out where the settings are introduced and link to the details.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is bfe3a06. Since that approval, the branch continued documentation-only work (FAQ fold/delete, terminology standardization, page collapse to /browsers/pools, Scale-page rewrite, pools-page dedupe). Latest delta (59fcb57 → bfe3a06) clarifies profile constraints in the browsers/pools.mdx intro (1 line). That does not raise risk.
Evidence (from full diff vs base)
25 files, all Mintlify docs: .mdx content plus docs.json nav/redirect updates (Reserved Browsers → single browsers/pools entry; FAQ removed; /browsers/pools/overview → /browsers/pools).
Net change about +178 / −189: terminology, guidance, example code blocks, page rename/dedupe, and related cross-links across pools, create, scale, pricing, concepts, and references.
Latest delta: 1 file, docs prose only (+1 / −1).
No application code, APIs, auth logic, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Apply review feedback: drop the intro's repeat of the settings list,
reword the borrowed/topped-up and "unavailable to everything else"
phrasing, stop naming profiles twice in the same limitation, spell out
that pool capacity comes off the organization's concurrency limit, and
use the documented default viewport in the examples.
Move Timeout behavior under Release, where reuse is discussed, and lead
with the practice: always release, with the timeout as a backstop.
Remove the "let it expire" option for rolling configuration, which
relied on idle sessions timing out.
Lead the profiles section with Managed Auth as the way to fill and
maintain a profile, then the one-identity vs per-task choice. Drop the
thin Configuration section.
Move the walkthrough code out — the full example and the per-user
step-by-step both belong in the quickstart — leaving the behavior and
the constraint behind. The page is 401 lines, down from 616.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is 0f19f9f. Since that approval, the branch continued documentation-only work (quickstart removal, FAQ fold/delete, terminology, page collapse to /browsers/pools, pool wording disambiguation, scale/home rewrites, pools page dedupe). Latest delta (bfe3a06 → 0f19f9f) edits a single file (browsers/pools.mdx): tightens the page by removing walkthrough code and redundant sections (−212 / +23). That does not raise risk.
Evidence (from full diff vs base)
26 files, all Mintlify docs: .mdx content plus docs.json nav/redirect updates (Reserved Browsers → single browsers/pools entry; FAQ removed; /browsers/pools/overview → /browsers/pools).
Terminology, guidance, and example code-block updates across pools, create, scale, pricing, concepts, and related pages; FAQ/overview deleted in favor of browsers/pools.mdx.
Latest delta: 1 file, docs prose/structure only.
No application code, APIs, auth, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
- Fold profiles into the configuration list as a link, dropping the
awkward two-constraints sentence; the profiles section covers it.
- Break the second paragraph into shorter sentences.
- Replace the Flush, Get details, List, and Delete sections with a
single "Managing a pool" table. They were pure call-and-description,
which the API reference already covers; the table keeps the behavior
notes (force delete, what flush spares) without four code groups.
This also absorbs the trailing API reference section.
- Fix the update warning, which still said "three ways" after the
expire-based option was removed.
Code drops from 57% of the page to 49%, and the page to 290 lines from
616 at the start of review — in line with comparable guide pages, which
all keep per-operation examples for the calls that carry behavior.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is 52b75d5. Since that approval, the branch continued documentation-only work (FAQ fold/delete, terminology standardization, page collapse to /browsers/pools, Scale-page rewrite, pools-page tightening). Latest delta (0f19f9f → 52b75d5) edits a single file (browsers/pools.mdx): folds Flush/Get/List/Delete code sections into a Managing table and fixes update-warning wording (−123 / +14). That does not raise risk.
Evidence (from full diff vs base)
26 files, all Mintlify docs: .mdx content plus docs.json nav/redirect updates (Reserved Browsers → single browsers/pools entry; FAQ removed; /browsers/pools/overview → /browsers/pools).
Net change +413 / −722: terminology, guidance, example code blocks, page rename/dedupe, and related cross-links across pools, create, scale, pricing, concepts, and references.
Latest delta: 1 file, docs prose/structure only.
No application code, APIs, auth logic, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Sizing sat between Release and Update, splitting the create/acquire/
release walkthrough from the operational sections, and left Profiles
stranded between two of them. Move Profiles up to close out the
"using a pool" block so the page reads as three groups: what it is,
using one, then tuning and operating one.
Three of the five limitations restated content covered later in the
page. Keep the list as an up-front gate but make those bullets point
at their sections instead of explaining again.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval remains in effect. Latest HEAD is 6f322a2. Diff vs merge base is still documentation-only: Mintlify .mdx pages plus docs.json nav/redirect updates.
Evidence (from diff only)
26 files, +413 / −722 — all .mdx or docs.json
Consolidates browser pools docs (browsers/pools.mdx), deletes old browsers/pools/overview.mdx and faq.mdx, updates cross-links and terminology
Adds a redirect /browsers/pools/overview → /browsers/pools and flattens sidebar entry in docs.json
Expands intro guidance in introduction/create.mdx and introduction/scale.mdx (examples and prose only)
No application code, CI, infra, auth, billing, or schema changes
No CODEOWNERS file in the repo
Risk factors
Factor
Assessment
Codepaths / production logic
None
Blast radius
Docs site content and navigation only
Infrastructure
None
Security / auth
None
Action
No approval change. Risk remains Very Low; not re-approving because an automation approval is already present.
- Say what you'd otherwise do instead of "configuring one per task":
the configuration goes on the pool rather than into every
browsers.create() call.
- Rework the acquisition paragraph so it flows as prose rather than
three clipped sentences.
- Frame releasing as a best practice rather than an instruction, and
drop the reuse aside from the timeout section.
- Trim the Managed Auth mention to a pointer; how it works belongs on
the auth pages.
- Put per-user profiles above refresh-on-profile-update, since it's the
more common case.
- Replace the operations table with a link to the API reference.
- Drop the quickstart link, which has no target on this branch.
- Pricing: idle pooled browsers incur no usage charges, not "disk
charges".
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval remains in effect. Latest HEAD is d75d11b. Diff vs merge base is still documentation-only: Mintlify .mdx pages plus docs.json nav/redirect updates.
Latest delta since the prior assessment (6f322a2 → d75d11b): prose edits in browsers/pools.mdx and info/pricing.mdx only (section reorder/trim; "disk charges" → "usage charges").
Evidence (from diff only)
26 files, +404 / −722 — all .mdx or docs.json
Consolidates browser pools docs (browsers/pools.mdx), deletes old browsers/pools/overview.mdx and faq.mdx, updates cross-links and terminology
Adds redirect /browsers/pools/overview → /browsers/pools and flattens sidebar entry in docs.json
Expands intro guidance in introduction/create.mdx and introduction/scale.mdx (examples and prose only)
No application code, CI, infra, auth, billing logic, or schema changes
No CODEOWNERS file in the repo
Risk factors
Factor
Assessment
Codepaths / production logic
None
Blast radius
Docs site content and navigation only
Infrastructure
None
Security / auth
None
Action
No approval change. Risk remains Very Low; not re-approving because an automation approval is already present.
- Refer to on-demand browsers rather than browsers.create() in prose,
and drop the size/fill-rate parameter mismatch: the code sample and
API reference own parameter names and defaults, not the prose.
- Cut the fill-rate link from five places to one, in Sizing, where
you'd act on it.
- Give flush its own short section under Update, where it's the remedy
for stale configuration, and restore the two links that pointed at it.
- Say "browser pool" at each section's first mention, keeping "the pool"
only for back-references; rename the Create, Update, and per-user
headings to match, updating the links that referenced them.
- Remove three more restatements: the Create lead repeated the Steps
block, the Update warning re-explained discard_all_idle, and the
per-user lead repeated the read-only paragraph above it.
- Soften releasing into a best practice rather than an instruction, and
trim the Managed Auth mention to a pointer.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval remains in effect. Latest HEAD is f6abf40. Diff vs merge base is still documentation-only: Mintlify .mdx pages plus docs.json nav/redirect updates.
Latest delta since the prior assessment (d75d11b → f6abf40): prose/structure polish in browsers/pools.mdx, plus two cross-link/anchor wording tweaks in auth/profiles.mdx and browsers/chrome-policies.mdx.
Evidence (from diff only)
26 files, +408 / −722 — all .mdx or docs.json
Consolidates browser pools docs (browsers/pools.mdx), deletes old browsers/pools/overview.mdx and faq.mdx, updates cross-links and terminology
Adds redirect /browsers/pools/overview → /browsers/pools and flattens sidebar entry in docs.json
Expands intro guidance in introduction/create.mdx and introduction/scale.mdx (examples and prose only)
No application code, CI, infra, auth, billing logic, or schema changes
No CODEOWNERS file in the repo
Risk factors
Factor
Assessment
Codepaths / production logic
None
Blast radius
Docs site content and navigation only
Infrastructure
None
Security / auth
None
Action
No approval change. Risk remains Very Low; not re-approving because an automation approval is already present.
The intro stated the same idea three times — configure once, get
pre-configured browsers — and never actually said what a browser pool
is. Replace it with three paragraphs doing one job each: what a browser
pool is, why acquiring is faster, and what it costs. The Chromium
restart becomes part of the start-up point rather than a third parallel
clause.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Risk assessment: Very Low
Verdict: Very Low risk — prior approval retained (risk did not increase).
Re-evaluation after synchronize
Previous automation approval was on bf5ab05. Latest HEAD is a4c7e45. Since that approval, the branch continued documentation-only work (FAQ fold/delete, terminology standardization, page collapse to /browsers/pools, Scale-page rewrite, pools-page restructuring). Latest delta (f6abf40 → a4c7e45) edits a single file (browsers/pools.mdx): rewrites the intro into a clearer definition / latency / cost framing. That does not raise risk.
Evidence (from full diff vs base)
26 files, all Mintlify docs: .mdx content plus docs.json nav/redirect updates (Reserved Browsers → single browsers/pools entry; FAQ removed; /browsers/pools/overview → /browsers/pools).
Terminology, guidance, and example code-block updates across pools, create, scale, pricing, concepts, and related pages; FAQ and old overview deleted in favor of one pools page.
Latest delta: 1 file, docs prose only (+4 / −2).
No application code, APIs, auth, infra, schema, deploy config, or model-prompt instruction files.
No CODEOWNERS file requiring a separate owner approval.
Why this level
Documentation-only surface with no production logic or shared runtime impact.
Blast radius limited to published docs/nav; easy to reason about and revert.
Actions taken
Risk unchanged at Very Low → did not dismiss prior approval.
Did not re-approve (approval already present).
Did not assign or request reviewers.
Sent by Cursor Automation: Assign PR reviewers
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Summary
Browser pools weren't surfaced where a user decides to go to production — the concept was called "Reserved Browsers" in the sidebar, and the Create page never mentioned them. And the pools page itself had grown into a tutorial and an API reference wearing one hat, explaining the same handful of facts three and four times over.
This PR is scoped to browser pools documentation. The end-to-end quickstart is #470 (stacked on this branch), and the broader docs IA rework — replacing Basics/Intermediate/Advanced with lifecycle groups — is tracked separately. (Merged
mainto pick up #469, which moved Chrome policies to a standalone page.)1. One name: "browser pools", and every other "pool" qualified. The API, SDKs, CLI, and dashboard already said "browser pools" — the docs were the outlier. Renamed the sidebar group, dropped "reserved browsers" as a product name, and swept bare "pool" → "browser pool" in prose. "Pool" is overloaded here, so the other senses are disambiguated too: "connection pool" on the curl networking limits, "managed proxy pool" on bot-detection. ("ISP pool" and the unikernels page's "warm pools" were already unambiguous.)
2. Not described as "warm". Per docs-team feedback on this PR, "warm" implies pools run hot and bill for idle time — the opposite of the actual benefit. Now "ready to use" / "pre-provisioned", and the pricing line leads with the benefit: "an idle browser pool costs nothing between tasks."
3. One page at
/browsers/pools. The section was three pages (overview + FAQ + Chrome policies); it's now one, served at/browsers/poolsrather than/browsers/pools/overview. The FAQ folded in, Chrome policies left via #469, the nav group collapsed to a single entry, and a redirect covers the old path. The changelog's bare/browsers/poolslinks — previously 404s — now resolve, because that's where the page actually lives.4. Deduped. The intro explained "config is pre-applied so acquisition is faster" four times; read-only profiles appeared three times; update/stale-config semantics three times, including a paragraph duplicated verbatim two paragraphs later;
refresh_on_profile_updatethree times. Merged the three profile sections into one "Profiles with browser pools", moved the stale-config warning to "Update a pool" where it belongs, replaced "Pool configuration options" with a short Configuration pointer, and moved Sizing next to the acquire/release lifecycle.5. Pitched where users move to production, workload-driven. An "On demand or from a browser pool" section on
introduction/create(build withbrowsers.create(), move to a pool once you're repeating the same task), plus pointers from the home page and Scale. Fundamentals first, then pools — not a day-one default, not an afterthought.6. Scale page rewritten. It was written pre-launch and framed pools around three co-equal factors with a blunt "<50 concurrency → don't bother" gate. Now: benefit (low-latency acquisition, reserved capacity, higher creation throughput; the concurrency-limit tradeoff) → when to use vs on-demand (workload signals, not thresholds) → sizing (links to the pools page), keeping the three architecture patterns and dropping their numeric gates.
7. Content gaps closed.
reuse: true(default) returns the same browser with cookies/storage/sessions intact, so it's fast but not isolated;reuse: falseis clean at the cost of a rebuild. Multi-tenant leak warning added.available_count, target 10–20% available; a small pool still pays off when acquisition latency matters, with no concurrency-number gate.start_urlthe only per-acquire override), read-only profiles, reserved capacity holds concurrency slots whether or not acquired, Start-Up/Enterprise only.fill_rate_per_minuteexample aligned with the documented 25% default (was 10, which read as a competing default).Verification
origin/main; resolveddocs.jsonand took main's canonicalbrowsers/chrome-policies.mdx.docs.jsonvalid; every nav page resolves to a file; the pools entry is a singlebrowsers/poolspage; no staleoverview/faq/policy-jsonnav refs./browsers/pools/overviewlinks repointed; a stale#create-a-pool-of-reserved-browsersanchor fixed; every in-page anchor resolves; externally-linked anchors preserved (#how-browser-pools-work,#create-a-pool,#update-a-pool,#sizing-a-browser-pool,#per-user-profiles-with-pools)./browsers/pools/overview→/browsers/pools(new),/browsers/pools/policy-json→/browsers/chrome-policies(from Move Chrome Policies to Advanced and clarify it applies to individual browsers #469).sizerequired onupdate. "Acquire isn't rate-limited" verified against the API's rate-limiter: onlyPOST /browsersis rate-limited.mint devnot booted in this environment, so the pages aren't visually confirmed. Worth a preview pass before merge.Related
🤖 Generated with Claude Code