diff --git a/packages/docs/docs/query.md b/packages/docs/docs/query.md
index 87da71e..ccb4efc 100644
--- a/packages/docs/docs/query.md
+++ b/packages/docs/docs/query.md
@@ -50,7 +50,9 @@ export const runtime = ReactRuntime.make(AppLive)
 
 The client owns the cache and its cleanup lifecycle. Individual queries can
 override `staleTime` and `refreshOnWindowFocus`; otherwise they inherit the
-client defaults.
+client defaults. Window-focus refresh also requires the optional
+`@effect/platform-browser` package, as described under
+[Staleness and cache lifetime](#staleness-and-cache-lifetime).
 
 ## Create a reactive query
 
@@ -268,8 +270,17 @@ const query = yield* Query.service({
 })
 ```
 
-Window focus resolves the current key again, subject to the same freshness
-check. The browser integration is ignored in non-browser environments.
+Window-focus refresh depends on the optional `@effect/platform-browser`
+integration. Install it in browser applications that use this behavior:
+
+```bash npm2yarn
+npm install @effect/platform-browser@beta
+```
+
+When the package is available, focusing the window resolves the current key
+again, subject to the same freshness check. Without it,
+`refreshOnWindowFocus` has no effect; the rest of the Query API continues to
+work normally. The integration is also ignored in non-browser environments.
 
 ## The Effect touch