From e7361078f3a90b73097a9b3f8eaa7b8c233972fa Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Sat, 2 May 2026 17:25:23 +0000
Subject: [PATCH] docs(pools): clarify profile updates do not propagate to idle
 pool browsers

---
 browsers/pools/faq.mdx | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx
index 6446f55..327abb5 100644
--- a/browsers/pools/faq.mdx
+++ b/browsers/pools/faq.mdx
@@ -24,6 +24,12 @@ When a browser from a pool is set to be destroyed (by reaching its specified `ti
 
 Yes, use `kernel.browserPools.update()`. By default, idle browsers are discarded and rebuilt with new configuration. Set `discard_all_idle: false` to only apply changes to newly created browsers.
 
+### If I update a profile's contents, will my pool's idle browsers pick up the change?
+
+No. Idle browsers in a pool are pre-loaded with the profile's contents at the time they were filled. Updating the profile (for example, re-saving auth state to the same `profile_id`) does not propagate to already-warmed browsers — only newly-filled browsers will use the updated profile.
+
+To force the pool to pick up new profile contents, either call `kernel.browserPools.flush()` to destroy idle browsers (the pool refills automatically), or call `kernel.browserPools.update()` with `discard_all_idle: true`.
+
 ### Should I set `reuse: true` or `reuse: false` when releasing?
 
 Use `reuse: true` (default) for efficiency. Only use `reuse: false` when you suspect browser state corruption or need a guaranteed clean browser session.