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

---
 packages/docs/docs/getting-started.md | 61 ++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 5 deletions(-)

diff --git a/packages/docs/docs/getting-started.md b/packages/docs/docs/getting-started.md
index 0f3eecb..ef07f77 100644
--- a/packages/docs/docs/getting-started.md
+++ b/packages/docs/docs/getting-started.md
@@ -86,27 +86,41 @@ provider so route components can be converted with the same runtime context.
 ## Write Your First Component
 
 Use `Component.make` when you want automatic tracing spans, or
-`Component.makeUntraced` when you only want the component behavior.
+`Component.makeUntraced` when you only want the component behavior. This creates
+an Effect-FC component, not a plain React component yet.
 
-```tsx title="src/Hello.tsx"
+```tsx title="src/HelloEffect.tsx"
 import { Effect } from "effect"
 import { Component } from "effect-fc"
-import { runtime } from "./runtime"
 
-const HelloEffect = Component.make("HelloEffect")(function* (props: {
+export const HelloEffect = Component.make("HelloEffect")(function* (props: {
   readonly name: string
 }) {
   const message = yield* Effect.succeed(`Hello, ${props.name}`)
 
   return <h1>{message}</h1>
 })
+```
+
+At this point `HelloEffect` can yield Effects, services, and scoped lifecycle
+work, but React cannot render it directly.
+
+## Apply A Runtime
+
+Use `Component.withRuntime` at the boundary where an Effect-FC component needs
+to become a regular React function component.
+
+```tsx title="src/Hello.tsx"
+import { Component } from "effect-fc"
+import { HelloEffect } from "./HelloEffect"
+import { runtime } from "./runtime"
 
 export const Hello = HelloEffect.pipe(
   Component.withRuntime(runtime.context),
 )
 ```
 
-`Hello` is now a regular React component:
+`Hello` is now a normal React component:
 
 ```tsx title="src/App.tsx"
 import { Hello } from "./Hello"
@@ -116,6 +130,43 @@ export function App() {
 }
 ```
 
+## Use Effect-FC Components Together
+
+Inside an Effect-FC component, other Effect-FC components are available through
+their `.use` effect. Yield `.use` to get a React component for the current
+runtime context, then render it like JSX.
+
+```tsx title="src/GreetingCardEffect.tsx"
+import { Component } from "effect-fc"
+import { HelloEffect } from "./HelloEffect"
+
+export const GreetingCardEffect = Component.make("GreetingCard")(
+  function* () {
+    const Hello = yield* HelloEffect.use
+
+    return (
+      <section>
+        <Hello name="Effect" />
+        <p>This component is still running inside Effect-FC.</p>
+      </section>
+    )
+  },
+)
+```
+
+Use `Component.withRuntime` only when you leave the Effect-FC tree and need a
+normal React component again:
+
+```tsx title="src/GreetingCard.tsx"
+import { Component } from "effect-fc"
+import { GreetingCardEffect } from "./GreetingCardEffect"
+import { runtime } from "./runtime"
+
+export const GreetingCard = GreetingCardEffect.pipe(
+  Component.withRuntime(runtime.context),
+)
+```
+
 ## Use Services
 
 Components can yield Effect services directly. Define services with Effect,