Document save_changes requirement for per-user pool profiles - #497
Merged
Conversation
The per-user browser pool flow said destroying the browser persists the user's profile changes, but save_changes defaults to false, so following the docs verbatim discards every user's session on release. Spell out the opt-in and add a TS/Python/Go example of the full acquire-attach-release cycle. Also scope the "profiles load read-only" limitation to the pool's own profile — a profile attached after acquiring is writable — and point that bullet at the per-user section rather than its parent, which describes the read-only case it is contrasting against.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
AnnaXWang
marked this pull request as ready for review
August 10, 2026 17:59
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Risk assessment: Very Low
Verdict: Very Low risk — approved.
Evidence (from diff vs main)
- 2 files changed, +64 / −3:
browsers/pools.mdx,auth/profiles.mdx - Documentation-only MDX edits: clarifies that per-user pool profile attach requires
save_changes: true, scopes the read-only limitation to the pool’s own profile, fixes an anchor link, and adds TS/Python/Go acquire → attach → release examples - No application code, config, infra, auth/billing logic, schemas, or shared libraries modified
Risk factors
| Factor | Assessment |
|---|---|
| Codepaths / blast radius | Docs site content only |
| Complexity | Small, localized copy + examples |
| Infra / ops / security | None |
| User-facing surface | Published docs only (correctness of API guidance; no runtime behavior change) |
Checks
- No
CODEOWNERSfile in repo — codeowner review not required for approval - No prior approvals to re-evaluate or dismiss
- No reviewers assigned by this automation
Action: Approve (Very Low).
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
The per-user browser pool flow on
/browsers/poolstells you to attach a profile after acquiring and release withreuse: false, then claims "Destroying it both persists that user's profile changes." It doesn't —save_changesdefaults tofalseon the profile attach, and the destroy-time save is gated on it, so anyone following the page verbatim silently discards every user's session on release.Changes
save_changes: true, and explain why the read-only rule doesn't apply here (the profile belongs to the browser, not the pool). Added a TypeScript/Python/Go example of the full acquire → attach → release cycle, which the section previously lacked.#profiles-with-browser-poolsto#per-user-profiles-with-browser-pools— the bullet promises "how to persist state per user" but was linking to the section that says persistence isn't possible./auth/profilesnotes: samesave_changes: trueomission in the bullet that cross-links to the pools page.Verification
Checked against the API source rather than inferred:
BrowserProfile.save_changesdefaults tofalse;BrowserPoolProfileomits it entirely and ignores it if sent.PATCH /browsers/{id}accepts a profile on a leased pooled session (rejected only when not leased) and carriessave_changesthrough to the session row.reuse: falsedestroys the session, and the destroy path only saves the profile whenProfile.SaveChangesis set.No change to the
refresh_on_profile_updatesection — its documented behavior (requires a pool profile, defaults to true when a profile is attached, forced false when the profile is cleared) matches the validation and PATCH resolution logic.Not rendered locally; the copy and code examples follow the existing conventions on both pages.
Note
Low Risk
Documentation-only changes with no runtime, API, or security impact.
Overview
Fixes documentation that implied per-user profile state is persisted when releasing a pooled browser with
reuse: false, without mentioning thatsave_changesdefaults tofalseon post-acquire profile attach.On
/browsers/pools, the per-user flow now states that pool-config profiles stay read-only while profiles attached afteracquirefollow normal browser rules, so attach must usesave_changes: trueor session data is discarded on destroy. Adds a TypeScript/Python/Go acquire →browsers.update→ release example. The limitations bullet scopes read-only behavior to the pool’s profile and links to#per-user-profiles-with-browser-pools. Removes the incorrect claim that destroy alone persists changes.On
/auth/profiles, the cross-link note now explicitly requiressave_changes: truewhen persisting per-user state through a pool.Reviewed by Cursor Bugbot for commit 948e372. Bugbot is set up for automated code reviews on this repo. Configure here.