Updated realtime docs to be much clearer

Author: D-K-P

docs/docs.json

@@ -137,7 +137,7 @@
               "realtime/run-object",
               "realtime/auth",
               {
-                "group": "React hooks (frontend)",
+                "group": "React hooks",
                 "pages": [
                   "realtime/react-hooks/overview",
                   "realtime/react-hooks/triggering",

docs/realtime/backend/overview.mdx

@@ -1,23 +1,22 @@
 ---
-title: Backend overview
+title: "Subscribe to tasks from your backend"
 sidebarTitle: Overview
-description: Using the Trigger.dev realtime API from your backend code
+description: "Subscribe to run progress, stream AI output, and react to task status changes from your backend code or other tasks."
 ---
 
 import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
 
-Use these backend functions to subscribe to runs and streams from your server-side code or other tasks.
+**Subscribe to runs from your server-side code or other tasks using async iterators.** Get status updates, metadata changes, and streamed data without polling.
 
-## Overview
+## What's available
 
-There are three main categories of functionality:
-
-- **[Subscribe functions](/realtime/backend/subscribe)** - Subscribe to run updates using async iterators
-- **[Metadata](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks)** - Update and subscribe to run metadata in real-time
-- **[Streams](/realtime/backend/streams)** - Read and consume real-time streaming data from your tasks
+| Category | What it does | Guide |
+|---|---|---|
+| **Progress and status** | Subscribe to run status, metadata, and tag changes | [Progress & status](/realtime/backend/subscribe) |
+| **Streaming data** | Read AI output, file chunks, or any continuous data from tasks | [Streaming](/realtime/backend/streams) |
 
 <Note>
-  To learn how to emit streams from your tasks, see our [Realtime Streams](/tasks/streams) documentation.
+  To learn how to emit streams from your tasks, see [Streaming data from tasks](/tasks/streams).
 </Note>
 
 ## Authentication

docs/realtime/backend/streams.mdx

@@ -1,13 +1,13 @@
 ---
-title: Streams
-sidebarTitle: Streams
-description: Read and consume real-time streaming data from your tasks in your backend
+title: "Stream data to your backend (AI, files)"
+sidebarTitle: "Streaming"
+description: "Read AI/LLM output, file chunks, and other streaming data from your Trigger.dev tasks in backend code."
 ---
 
-The Streams API allows you to read streaming data from your Trigger.dev tasks in your backend code. This is particularly useful for consuming AI/LLM outputs, progress updates, or any other real-time data that your tasks emit.
+**Read streaming data from your tasks in backend code.** Consume AI completions as they generate, process file chunks, or handle any continuous data your tasks produce.
 
 <Note>
-  To learn how to emit streams from your tasks, see our [Realtime Streams](/tasks/streams) documentation. For frontend applications using React, see our [React hooks streams documentation](/realtime/react-hooks/streams).
+  To emit streams from your tasks, see [Streaming data from tasks](/tasks/streams). For React components, see [Streaming in React](/realtime/react-hooks/streams).
 </Note>
 
 ## Reading streams

docs/realtime/backend/subscribe.mdx

@@ -1,10 +1,10 @@
 ---
-title: Subscribe functions
-sidebarTitle: Subscribe
-description: Subscribe to run updates using async iterators
+title: "Progress and status updates (backend)"
+sidebarTitle: "Progress & status"
+description: "Subscribe to run status changes, metadata updates, and tag changes from your backend code using async iterators."
 ---
 
-These functions allow you to subscribe to run updates from your backend code. Each function returns an async iterator that yields run objects as they change.
+**Subscribe to runs from your backend and get updates whenever status, metadata, or tags change.** Each function returns an async iterator that yields the run object on every change.
 
 ## runs.subscribeToRun
 

docs/realtime/how-it-works.mdx

@@ -1,7 +1,7 @@
 ---
-title: How it works
-sidebarTitle: How it works
-description: Technical details about how the Trigger.dev Realtime API works
+title: "How Realtime works"
+sidebarTitle: "How it works"
+description: "Technical architecture behind Trigger.dev's real-time run updates, built on Electric SQL and PostgreSQL syncing."
 ---
 
 ## Architecture

docs/realtime/overview.mdx

@@ -1,39 +1,66 @@
 ---
 title: Realtime overview
 sidebarTitle: Overview
-description: Using the Trigger.dev Realtime API to trigger and/or subscribe to runs in real-time.
+description: "Subscribe to run state changes (status, metadata, tags) in real time from your frontend or backend."
 ---
 
-Trigger.dev Realtime allows you to trigger, subscribe to, and get real-time updates for runs. This is useful for monitoring runs, updating UIs, and building real-time dashboards.
+**Realtime subscriptions let you watch run state as it changes: status transitions, metadata updates, and tag changes.** You get the full [run object](/realtime/run-object) pushed to your code whenever something changes. No polling.
 
-You can subscribe to real-time updates for different scopes of runs:
+For streaming continuous data from tasks (AI completions, progress chunks, file data), see [Streams](/tasks/streams). Streams and Realtime work together but solve different problems.
 
-- **Specific runs** - Monitor individual run progress by run ID
-- **Runs with specific tags** - Track all runs that have certain [tags](/tags) (e.g., all runs tagged with `user:123`)
-- **Batch runs** - All runs within a specific batch
-- **Trigger + subscribe combos** - Trigger a task and immediately subscribe to its run (frontend only)
+## How is Realtime different from Streams?
 
-Once subscribed, you'll receive the complete [run object](/realtime/run-object) with automatic real-time updates whenever the [run changes](/realtime/how-it-works#run-changes), including:
+| | Realtime subscriptions | Streams |
+|---|---|---|
+| **What it sends** | Run state (status, metadata, tags) | Arbitrary data you define (AI tokens, progress, files) |
+| **When it updates** | On state changes | Continuously while the task runs |
+| **Typical use case** | Progress bars, status badges, dashboards | AI chat responses, live logs, file processing |
+| **React hook** | [`useRealtimeRun`](/realtime/react-hooks/subscribe) | [`useRealtimeStream`](/realtime/react-hooks/streams) |
+| **Define in task code?** | No, automatic | Yes, using `streams.define()` |
 
-- **Status changes** - queued → executing → completed, etc.
-- **Metadata updates** - Custom progress tracking, status updates, user data, etc. ([React hooks](/realtime/react-hooks/subscribe#using-metadata-to-show-progress-in-your-ui) | [backend](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks))
-- **Tag changes** - When [tags](/tags) are added or removed from the run
-- **Realtime Streams** - Stream real-time data from your tasks, perfect for AI/LLM outputs and progress updates. ([Learn more](/tasks/streams) | [React hooks](/realtime/react-hooks/streams) | [Backend](/realtime/backend/streams))
+You can use both at the same time. Subscribe to a run's status with Realtime while also streaming AI output with Streams.
+
+## What you can subscribe to
+
+- **Specific runs** by run ID
+- **Runs with specific tags** (e.g., all runs tagged with `user:123`). [More on tags](/tags)
+- **Batch runs** within a specific batch
+- **Trigger + subscribe combos** that trigger a task and immediately subscribe (frontend only)
+
+Once subscribed, you get updates for:
+
+- **Status changes** like queued, executing, completed, failed
+- **Metadata updates** for custom progress tracking ([React hooks](/realtime/react-hooks/subscribe#using-metadata-to-show-progress-in-your-ui) | [backend](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks))
+- **Tag changes** when [tags](/tags) are added or removed
 
 ## Using Realtime in your applications
 
 ### Authentication
 
-All Realtime subscriptions require authentication so you can securely trigger and subscribe to runs. See our [authentication guide](/realtime/auth) for more details.
+All Realtime subscriptions require authentication. See the [authentication guide](/realtime/auth) for setup.
+
+### Frontend (React hooks)
+
+Use `@trigger.dev/react-hooks` to build UIs that update as runs execute.
+
+→ **[React hooks guide](/realtime/react-hooks/)**
+
+### Backend
+
+Subscribe to runs from your backend code, other tasks, or serverless functions.
+
+→ **[Backend guide](/realtime/backend)**
+
+## Frequently asked questions
 
-### Frontend implementation
+### What's the difference between Realtime and Streams?
 
-Use our React hooks to build real-time UIs that update as runs execute. Ideal for progress bars, status indicators, and live dashboards.
+Realtime tracks **run state**: status, metadata, and tags. Streams pipe **continuous data** (like AI completions or progress updates) from a running task to your frontend or backend. Use Realtime for "is my task done yet?" and Streams for "show me the AI output as it generates."
 
-→ **[See our React hooks guide](/realtime/react-hooks/)**
+### Do I need to set up anything in my task for Realtime?
 
-### Backend implementation
+No. Realtime subscriptions work automatically for any task. Just subscribe by run ID, tag, or batch from your frontend or backend. Streams require you to define them in your task code with `streams.define()`.
 
-Use our server-side SDK to subscribe to runs from your backend code, other tasks, or serverless functions. Perfect for triggering workflows, sending notifications, or updating databases based on run status changes.
+### Can I use Realtime and Streams together?
 
-→ **[See our Backend guide](/realtime/backend)**
+Yes. A common pattern is subscribing to a run's status with Realtime (to show a progress indicator) while also streaming AI output with Streams (to display tokens as they arrive).

docs/realtime/react-hooks/overview.mdx

@@ -1,12 +1,12 @@
 ---
-title: React hooks overview
+title: "React hooks for real-time task updates"
 sidebarTitle: Overview
-description: Using the Trigger.dev Realtime API from your React applications.
+description: "Subscribe to background task progress, stream AI responses, and trigger tasks from React components using @trigger.dev/react-hooks."
 ---
 
 import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
 
-Our React hooks package provides a set of hooks that make it easy to interact with the Trigger.dev Realtime API from your React applications. You can use these hooks to subscribe to real-time updates, and trigger tasks from your frontend.
+**`@trigger.dev/react-hooks` gives your React components live access to background tasks.** Subscribe to run progress, stream AI output as it generates, or trigger tasks directly from the browser.
 
 ## Installation
 
@@ -55,19 +55,19 @@ Learn more about [generating and managing tokens in our authentication guide](/r
 
 ## Available hooks
 
-We provide several categories of hooks:
-
-- **[Triggering hooks](/realtime/react-hooks/triggering)** - Trigger tasks from your frontend application
-- **[Subscribe hooks](/realtime/react-hooks/subscribe)** - Subscribe to runs, batches, metadata, and more
-- **[Streams hooks](/realtime/react-hooks/streams)** - Subscribe to real-time streams from your tasks
-- **[SWR hooks](/realtime/react-hooks/swr)** - Fetch data once and cache it using SWR
+| Hook category | What it does | Guide |
+|---|---|---|
+| **Trigger hooks** | Trigger tasks from the browser | [Triggering](/realtime/react-hooks/triggering) |
+| **Progress and status** | Subscribe to run status, metadata, and tags | [Progress and status](/realtime/react-hooks/subscribe) |
+| **Streaming data** | Consume AI output, file chunks, or any continuous data | [Streaming](/realtime/react-hooks/streams) |
+| **SWR hooks** | One-time fetch with caching (not recommended for most cases) | [SWR](/realtime/react-hooks/swr) |
 
 ## SWR vs Realtime hooks
 
-We offer two "styles" of hooks: SWR and Realtime. The SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. The Realtime hooks use [Trigger.dev Realtime](/realtime) to subscribe to updates in real-time.
+We offer two "styles" of hooks: SWR and Realtime. SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. Realtime hooks use [Trigger.dev Realtime](/realtime) to subscribe to updates as they happen.
 
 <Note>
   It can be a little confusing which one to use because [swr](https://swr.vercel.app/) can also be
   configured to poll for updates. But because of rate-limits and the way the Trigger.dev API works,
-  we recommend using the Realtime hooks for most use-cases.
+  we recommend using the Realtime hooks for most use cases.
 </Note>

docs/realtime/react-hooks/streams.mdx

@@ -1,14 +1,13 @@
 ---
-title: Streams hooks
-sidebarTitle: Streams
-description: Subscribe to real-time streams from your tasks in React components
+title: "Stream data to React (AI, files, progress)"
+sidebarTitle: "Streaming"
+description: "Display AI/LLM output token by token, stream file chunks, or pipe any continuous data from a background task into your React components."
 ---
 
-These hooks allow you to consume real-time streams from your tasks. Streams are useful for displaying AI/LLM outputs as they're generated, or any other real-time data from your tasks.
+**Display AI responses as they generate, stream file processing results, or pipe any continuous data from a running task into your React components.** Unlike [progress and status hooks](/realtime/react-hooks/subscribe) (which track run state), streaming hooks give you the raw data your task produces while it runs.
 
 <Note>
-  To learn how to emit streams from your tasks, see our [Realtime Streams](/tasks/streams)
-  documentation.
+  To learn how to emit streams from your tasks, see [Streaming data from tasks](/tasks/streams).
 </Note>
 
 ## useRealtimeStream (Recommended)
@@ -151,7 +150,7 @@ const { parts, error } = useRealtimeStream<string>(runId, {
 });
 ```
 
-For more information on defining and using streams, see the [Realtime Streams](/tasks/streams) documentation.
+For more information on defining and using streams, see the [Streaming data from tasks](/tasks/streams) documentation.
 
 ## useInputStreamSend
 
@@ -430,3 +429,21 @@ export function MyComponent({
 All other options (accessToken, baseURL, enabled, id) work the same as the other realtime hooks.
 
 For the newer `useRealtimeStream` hook, use the `throttleInMs` option instead (see [options above](#options)).
+
+## Frequently asked questions
+
+### How do I stream AI/LLM responses from a background task to React?
+
+Define a typed stream in your task with `streams.define<string>()`, pipe your AI SDK response to it with `.pipe()`, then consume it in your component with `useRealtimeStream`. See [Streaming data from tasks](/tasks/streams) for the task-side setup.
+
+### What's the difference between streaming and subscribing to runs?
+
+[Subscribing](/realtime/react-hooks/subscribe) tracks **run state** (status, metadata, tags). Streaming (this page) pipes **continuous data** your task produces. Use subscribing for progress bars and status badges. Use streaming for AI chat output, live logs, or file processing results. You can use both at the same time.
+
+### Can I send data back into a running task from React?
+
+Yes. Use the `useInputStreamSend` hook to send data into a running task's input stream. This is useful for cancel buttons, user approvals, or any interactive flow. See [Input Streams](/tasks/streams#input-streams) for the full guide.
+
+### Do streams work with the Vercel AI SDK?
+
+Yes. You can pipe a Vercel AI SDK `streamText` response directly into a Trigger.dev stream using `.pipe()`. The [Streaming data from tasks](/tasks/streams) page has a complete AI streaming example.

docs/realtime/react-hooks/subscribe.mdx

@@ -1,21 +1,21 @@
 ---
-title: Subscribing to runs
-sidebarTitle: Subscribe
-description: Get live updates from runs, batches, metadata, and more in your frontend application.
+title: "Progress and status updates in React"
+sidebarTitle: "Progress & status"
+description: "Build progress bars, status indicators, and live dashboards by subscribing to background task updates from React components."
 ---
 
-These hooks allow you to subscribe to runs, batches, and streams using [Trigger.dev Realtime](/realtime). They automatically include real-time updates for run status, metadata, output, and other properties.
+**Subscribe to a run and your component re-renders whenever its status, metadata, or tags change.** Build progress bars, deployment monitors, or any UI that needs to reflect what a background task is doing right now.
 
-## Hooks
+For streaming continuous data (AI tokens, file chunks), see [Streaming data](/realtime/react-hooks/streams) instead.
 
-## Triggering + Realtime hooks
+## Trigger + subscribe combo hooks
 
-For triggering tasks and immediately subscribing to their runs, we provide combo hooks, details on how to use them can be found in the [triggering](/realtime/react-hooks/triggering) section.
+Trigger a task and immediately subscribe to its run. Details in the [triggering](/realtime/react-hooks/triggering) section.
 
 - **[`useRealtimeTaskTrigger`](/realtime/react-hooks/triggering#userealtimetasktrigger)** - Trigger a task and subscribe to the run
 - **[`useRealtimeTaskTriggerWithStreams`](/realtime/react-hooks/triggering#userealtimetasktriggerwithstreams)** - Trigger a task and subscribe to both run updates and streams
 
-## Other Realtime subscription hooks
+## Subscribe hooks
 
 ### useRealtimeRun
 
@@ -654,3 +654,21 @@ export function MyComponent({
 ```
 
 This allows you to change the ID of the subscription based on some state. Passing in a different ID will unsubscribe from the current subscription and subscribe to the new one (and remove any cached data).
+
+## Frequently asked questions
+
+### How do I show a progress bar for a background task in React?
+
+Use `metadata.set()` inside your task to update a progress value, then read it with `useRealtimeRun` in your component. The hook re-renders your component on every metadata change. See [Using metadata to show progress](#using-metadata-to-show-progress-in-your-ui) above for a complete example.
+
+### What's the difference between subscribing to runs and streaming data?
+
+Subscribing (this page) gives you **run state**: status, metadata, and tags. It's for progress bars, status badges, and dashboards. [Streaming](/realtime/react-hooks/streams) gives you **continuous data** like AI tokens or file chunks. Use subscribing for "how far along is my task?" and streaming for "show me the output as it generates."
+
+### Can I subscribe to multiple runs at once?
+
+Yes. Use `useRealtimeRunsWithTag` to subscribe to all runs with a specific tag (e.g., `user:123`), or `useRealtimeBatch` for all runs in a batch. Each yields an array of run objects that update in real time.
+
+### Do I need to set up polling or WebSockets?
+
+No. The hooks handle the connection automatically using Trigger.dev's Realtime infrastructure (built on [Electric SQL](/realtime/how-it-works)). Just pass a run ID and an access token.

docs/realtime/react-hooks/triggering.mdx

@@ -1,10 +1,10 @@
 ---
-title: Trigger hooks
+title: "Trigger tasks from React"
 sidebarTitle: Triggering
-description: Triggering tasks from your frontend application.
+description: "Trigger background tasks from React components and optionally subscribe to their progress or stream their output."
 ---
 
-We provide a set of hooks that can be used to trigger tasks from your frontend application.
+Trigger tasks directly from your React components. You can fire-and-forget, or trigger and immediately subscribe to the run's progress or streamed output.
 
 <Note>
   For triggering tasks from your frontend, you need to use “trigger” tokens. These can only be used