docs(pools): document per-user profile persistence through pools

[dprevoznik]

Summary

Customers who want to load many per-user profiles through a pool's pre-warmed browsers were reading the pools FAQ / profiles docs and concluding that profile write-back is unsupported for pooled browsers entirely. The docs only documented the negative (pool-config profiles are read-only) and never documented the supported pattern.

This clarifies the distinction and documents the recommended pattern:

1. Create the pool with no profile
2. Acquire a browser
3. Attach the per-user profile with save_changes: true via kernel.browsers.update()
4. Release with reuse: false — destroys the browser, which persists the profile changes and prevents state leaking to the next user

Changes

• browsers/pools/overview.mdx — new "Per-user profiles with pools" section with the full flow and TS/Python/Go examples.
• browsers/pools/faq.mdx — rewrote "Can pooled browsers save changes back to a profile?" to separate pool-config (read-only) from per-session (persists), and added a new FAQ for the per-user pattern.
• auth/profiles.mdx — added a note to "Loading a profile into an existing browser" and refined the save_changes note in Notes to cover update() + reuse: false, all cross-linking the new section.

Docs-only; no code paths changed. Not run locally with mintlify dev; anchor slug and cross-links verified by inspection.

---

Note

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

Overview
Clarifies that pool-config profiles stay read-only, while per-user profile write-back is supported when you attach a profile after acquire and tear down the session on release.

Adds a Per-user profiles with pools section in browsers/pools/overview.mdx with the four-step flow (profile-free pool → acquire → kernel.browsers.update() with save_changes: true → release with reuse: false) plus TypeScript, Python, and Go examples, and notes that reuse: false refills the pool.

Rewrites the pools FAQ Can pooled browsers save changes back to a profile? to separate pool-level vs per-session behavior and points to the new overview section.

In auth/profiles.mdx, adds a cross-link from loading profiles into existing browsers and expands the save_changes note to cover browsers.update() and the pool + reuse: false pattern.

^{Reviewed by Cursor Bugbot for commit d4ebf81. 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	🟢 Ready	View Preview	Jul 21, 2026, 10:39 AM

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Kernel	🟡 Building	–	Jul 21, 2026, 10:38 AM

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

[cursor]

Stale comment

Risk assessment: Very Low

The current diff only updates three MDX documentation pages. It adds explanations and TypeScript, Python, and Go examples for attaching per-user profiles to acquired pooled browsers; it doesn't change production code, API schemas, infrastructure, authentication, permissions, or site configuration. The latest update only reorders existing documentation sections, so risk hasn't increased since the prior approval.

No CODEOWNERS file is present. The PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

The current diff modifies only three MDX documentation pages. It adds guidance and TypeScript, Python, and Go examples for attaching per-user profiles to acquired pooled browsers; it doesn't change production code, API schemas, infrastructure, authentication, permissions, or site configuration. The latest update changes one sentence to clarify that a pool-level profile can't represent many users in one pool, so the risk hasn't increased since the prior approval.

No CODEOWNERS file is present. The PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

The full diff changes only three MDX documentation pages, adding explanatory text and TypeScript, Python, and Go examples for per-user profiles with browser pools. It doesn't modify production code, API schemas, site configuration, infrastructure, authentication, permissions, or model prompts. The newest commit only clarifies comments in the examples about creating the pool separately from per-user workload execution, so the risk hasn't increased.

No CODEOWNERS file or outstanding review request is present. This PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

The full diff modifies only three MDX documentation pages. It adds guidance plus TypeScript, Python, and Go examples for using per-user profiles with browser pools; it doesn't change production code, API schemas, site configuration, infrastructure, authentication, permissions, or model prompts. The latest revision only clarifies example comments about declaring the pool separately from per-user workload execution, so the risk hasn't increased.

No CODEOWNERS file or outstanding review request is present. The PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[AnnaXWang]

This feels like it comes out of nowhere, maybe we need to say "to use profiles with browser pools, read: "

[cursor]

Stale comment

Risk assessment: Very Low

The full diff modifies only three MDX documentation pages, adding guidance and TypeScript, Python, and Go examples for using per-user profiles with browser pools. It doesn't change production code, API schemas, site configuration, infrastructure, authentication, permissions, or model prompts. The latest revision only removes a duplicate FAQ entry, so the risk hasn't increased.

No CODEOWNERS file or outstanding review request is present. The PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk assessment: Very Low

The full diff changes only three MDX documentation pages. It adds guidance and TypeScript, Python, and Go examples for persisting per-user profiles through browser pools; it doesn't modify production code, API schemas, site configuration, infrastructure, authentication, permissions, or model prompts. Since the prior assessment, the only change is a one-sentence clarification in auth/profiles.mdx, so risk hasn't increased.

No CODEOWNERS file or requested reviewer is present. The PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes using high effort 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 e1b54a3. Configure here.}

[cursor]

Risk assessment: Very Low

The full diff modifies only three MDX documentation pages, adding profile-persistence guidance and TypeScript, Python, and Go examples for browser pools. It doesn't change production code, API schemas, site configuration, infrastructure, authentication, permissions, or model prompts. The latest update replaces a longer duplicated note with a short link to the relevant FAQ, so risk hasn't increased.

No CODEOWNERS file or requested reviewer is present. The PR is already approved, so I haven't submitted another approval or revoked the existing one.

  

_{Sent by Cursor Automation: Assign PR reviewers}