From d3525aaad7b5b0033351d2ac86691078602579ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20Valverd=C3=A9?= <julien.valverde@mailo.com>
Date: Tue, 9 Jun 2026 11:09:47 +0200
Subject: [PATCH] Docs

---
 packages/docs/docs/getting-started.md | 28 ++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/packages/docs/docs/getting-started.md b/packages/docs/docs/getting-started.md
index 388ac9f..192fc1a 100644
--- a/packages/docs/docs/getting-started.md
+++ b/packages/docs/docs/getting-started.md
@@ -204,9 +204,14 @@ export const MountedMessageView = Component.make("MountedMessage")(
 )
 ```
 
-Use `Component.useOnMount` for work that should run once for the component
-instance and return a cached value. Use `Component.useOnChange` when the scoped
-work should be recreated when dependencies change.
+Use `Component.useOnMount` when the component needs a value produced by an
+Effect during its first render. The value is then cached for the component
+instance.
+
+Use `Component.useOnChange` when render needs the value computed by
+scoped work that depends on changing inputs. When a dependency changes, React
+re-renders the component and the hook computes the next value during that
+render.
 
 ```tsx
 import { Console, Effect } from "effect"
@@ -243,18 +248,22 @@ need a lifecycle that is narrower than the whole component instance.
 
 The most common Effect-FC hooks are:
 
-- `Component.useOnMount`: run an Effect once for the component instance and
-  return its value.
+Unlike plain React hooks, Effect-FC hooks return Effects. Use `yield*` to run
+them inside the component body.
+
+- `Component.useOnMount`: run an Effect once during the component's first render
+  after mount, and return its value. The Effect must be synchronous.
 
 ```tsx
 const initialData = yield* Component.useOnMount(() => loadInitialData)
 ```
 
-- `Component.useOnChange`: run an Effect again when dependencies change and
-  return its latest value.
+- `Component.useOnChange`: when a dependency changes, React re-renders the
+  component and the Effect is run again inside the component body. It returns
+  the latest value, so the Effect must be synchronous too.
 
 ```tsx
-const user = yield* Component.useOnChange(() => fetchUser(id), [id])
+const label = yield* Component.useOnChange(() => formatUserLabel(id), [id])
 ```
 
 - `Component.useReactEffect`: Effect-powered `React.useEffect` with scoped
@@ -264,7 +273,8 @@ const user = yield* Component.useOnChange(() => fetchUser(id), [id])
 yield* Component.useReactEffect(() => subscribe(id), [id])
 ```
 
-- `Component.useReactLayoutEffect`: Effect-powered `React.useLayoutEffect`.
+- `Component.useReactLayoutEffect`: Effect-powered `React.useLayoutEffect` with scoped
+  finalizers.
 
 ```tsx
 yield* Component.useReactLayoutEffect(() => measure(ref), [])