Document safe profile writer coordination

[IlyaasK]

What

• explain that profile saves replace the complete stored state rather than merging it
• document that the browser session ending last wins when multiple sessions save the same profile
• show how to find active writers with GET /browsers?status=active&query=<profileId> and profile_save_changes
• require an exact profile.id match because query searches multiple browser fields
• call out that concurrent workers still need a lock or lease around the check and browser creation

Why

kernel/kernel#3177 exposes profile_save_changes in browser responses. Customers can now identify active sessions that may overwrite a profile, but the Profiles guide did not explain the overwrite semantics or how to use the new field safely.

Customer impact

Customers get a concrete TypeScript, Python, and Go pattern for detecting active profile writers and guidance for preventing two workers from writing the same profile concurrently.

Related

• KERNEL-1687 — Expose active save_changes writers for a profile via the sessions API

Verification

• npx --yes mint@latest broken-links
• git diff --check

The generated API reference is unchanged and continues to update from the deployed OpenAPI specification.

---

Note

Low Risk
Documentation-only changes to the Profiles guide with no runtime or API behavior impact.

Overview
Adds a Prevent concurrent profile writes section to the Profiles guide that explains profile saves replace the full stored state (no merge) and that the session that ends last wins when multiple browsers use save_changes: true.

Documents how to detect active writers via GET /browsers?status=active&query=<profileId> and profile_save_changes, with TypeScript, Python, and Go examples that also filter on an exact profile.id because query can match other fields. Notes that workers still need a lock or lease around the list check and browser creation.

The Notes bullet on parallel profile use is tightened to match the same overwrite semantics.

^{Reviewed by Cursor Bugbot for commit 431755f. 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	Aug 10, 2026, 7:14 PM

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Error		Aug 10, 2026 7:13pm

[cursor]

Risk assessment: Very Low

Verdict: Approve

Evidence (from diff only)

• 1 file changed: auth/profiles.mdx (+63 / −1)
• Documentation-only update on the Profiles guide: new “Prevent concurrent profile writes” section, TS/Python/Go examples for listing active writers via profile_save_changes, and a Notes bullet clarifying last-write-wins overwrite semantics
• No application code, API implementation, config, CI, or infrastructure changes

Risk factors

Factor	Assessment
Codepaths / production logic	None modified
Blast radius	Docs site content only
Complexity	Straightforward guide + examples
Infra / security / auth model	Unaffected
User-facing surface	Documentation only

Decision

Fits Very Low criteria (documentation-only, small scoped diff, no runtime or shared-system impact). No CODEOWNERS file requiring additional ownership review. No prior approvals on this PR.

Action: Approved.

  

_{Sent by Cursor Automation: Assign PR reviewers}