docs(api): clarify reuse/discard_all_idle pool config staleness

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 125
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-ebbe079bb2542625826422afd876a3e8b499c579cf45efc5fd50e7982d34df7d.yml
-openapi_spec_hash: db850b61a0d71fe9f4b642df8782d7ae
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-83323f87ab825547b6cd11caa46e2643ebb0a68bbd326d4e07ccab970638fc03.yml
+openapi_spec_hash: 69ed04a66b4ef68e97f7bdc07dfe6df2
 config_hash: 06186eb40e0058a2a87ac251fc07415d

browserpool.go

@@ -495,8 +495,12 @@ func (r *BrowserPoolNewParamsProfile) UnmarshalJSON(data []byte) error {
 }
 
 type BrowserPoolUpdateParams struct {
-	// Whether to discard all idle browsers and rebuild the pool immediately. Defaults
-	// to false.
+	// Whether to discard all idle browsers and rebuild them immediately with the new
+	// configuration. Defaults to false. Only browsers that are idle when the update
+	// runs are rebuilt. A browser that is in use during the update keeps its original
+	// configuration, and if it is later released with `reuse: true` it returns to the
+	// pool with that stale configuration until it is discarded (by this flag on a
+	// later update, or by flushing the pool).
 	DiscardAllIdle param.Opt[bool] `json:"discard_all_idle,omitzero"`
 	// Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for
 	// most organizations but can be raised per-organization, so only the lower bound
@@ -655,7 +659,10 @@ type BrowserPoolReleaseParams struct {
 	// Browser session ID to release back to the pool
 	SessionID string `json:"session_id" api:"required"`
 	// Whether to reuse the browser instance or destroy it and create a new one.
-	// Defaults to true.
+	// Defaults to true. A reused browser keeps the configuration it was created with,
+	// so it does not pick up pool configuration changes made while it was in use.
+	// Release with `reuse: false`, or flush the pool afterward, to rebuild it with the
+	// current configuration.
 	Reuse param.Opt[bool] `json:"reuse,omitzero"`
 	paramObj
 }