triggerdotdev · D-K-P · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026
diff --git a/docs/docs.json b/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",
@@ -642,6 +642,10 @@
       "source": "/trigger-config",
       "destination": "/config/config-file"
     },
+    {
+      "source": "/guides/frameworks",
+      "destination": "/guides/frameworks/nextjs"
+    },
     {
       "source": "/guides/frameworks/introduction",
       "destination": "/guides/introduction"

diff --git a/docs/errors-retrying.mdx b/docs/errors-retrying.mdx
@@ -12,6 +12,8 @@ You can configure retrying in two ways:
 1. In your [trigger.config file](/config/config-file) you can set the default retrying behavior for all tasks.
 2. On each task you can set the retrying behavior.
 
+<Note>Task-level retry settings override the defaults in your `trigger.config` file.</Note>
+
 <Note>
   By default when you create your project using the CLI init command we disabled retrying in the DEV
   environment. You can enable it in your [trigger.config file](/config/config-file).

diff --git a/docs/guides/frameworks/nextjs.mdx b/docs/guides/frameworks/nextjs.mdx
@@ -45,7 +45,7 @@ For more information on authenticating with Trigger.dev, see the [API keys page]
 
 ## Triggering your task in Next.js
 
-Here are the steps to trigger your task in the Next.js App and Pages router and Server Actions. Alternatively, check out this repo for a [full working example](https://github.com/triggerdotdev/example-projects/tree/main/nextjs/server-actions/my-app) of a Next.js app with a Trigger.dev task triggered using a Server Action.
+Here are the steps to trigger your task in the Next.js App and Pages router and Server Actions.
 
 <Tabs>
 
@@ -432,5 +432,18 @@ You can test your revalidation task in the Trigger.dev dashboard on the testing
     <NextjsTroubleshootingMissingApiKey/>
     <NextjsTroubleshootingButtonSyntax/>
 
+## Realtime updates with React hooks
+
+The `@trigger.dev/react-hooks` package lets you subscribe to task runs from your React components. Show progress bars, stream AI responses, or display run status in real time.
+
+<CardGroup cols={2}>
+  <Card title="React hooks" icon="react" href="/realtime/react-hooks/overview">
+    Hooks for subscribing to runs, streaming data, and triggering tasks from the frontend.
+  </Card>
+  <Card title="Streams" icon="wave-pulse" href="/tasks/streams">
+    Pipe continuous data (like AI completions) from your tasks to the client while they run.
+  </Card>
+</CardGroup>
+
 <VercelDocsCards />
 <UsefulNextSteps />
diff --git a/docs/guides/frameworks/remix.mdx b/docs/guides/frameworks/remix.mdx
@@ -197,6 +197,19 @@ The `vercel-build` script in `package.json` is specific to Remix projects on Ver
 
 The `runtime: "edge"` configuration in the API route allows for better performance on Vercel's Edge Network.
 
+## Realtime updates with React hooks
+
+The `@trigger.dev/react-hooks` package lets you subscribe to task runs from your React components. Show progress bars, stream AI responses, or display run status in real time.
+
+<CardGroup cols={2}>
+  <Card title="React hooks" icon="react" href="/realtime/react-hooks/overview">
+    Hooks for subscribing to runs, streaming data, and triggering tasks from the frontend.
+  </Card>
+  <Card title="Streams" icon="wave-pulse" href="/tasks/streams">
+    Pipe continuous data (like AI completions) from your tasks to the client while they run.
+  </Card>
+</CardGroup>
+
 ## Additional resources for Remix
 
 <Card

diff --git a/docs/quick-start.mdx b/docs/quick-start.mdx
@@ -1,15 +1,57 @@
 ---
-title: "Quick start"
-description: "How to get started in 3 minutes using the CLI and SDK."
+title: "Quick start: add Trigger.dev to your project"
+sidebarTitle: "Quick start"
+description: "Set up Trigger.dev in your existing project in under 3 minutes. Install the SDK, create your first background task, and trigger it from your code."
 ---
 
-import CliInitStep from '/snippets/step-cli-init.mdx';
-import CliDevStep from '/snippets/step-cli-dev.mdx';
-import CliRunTestStep from '/snippets/step-run-test.mdx';
-import CliViewRunStep from '/snippets/step-view-run.mdx';
+import CliInitStep from "/snippets/step-cli-init.mdx";
+import CliDevStep from "/snippets/step-cli-dev.mdx";
+import CliRunTestStep from "/snippets/step-run-test.mdx";
+import CliViewRunStep from "/snippets/step-view-run.mdx";
 
+## Set up with AI
 
+Using an AI coding assistant? Copy this prompt and paste it into Claude Code, Cursor, Copilot, Windsurf, or any AI tool. It'll handle the setup for you.
 
+<Accordion title="Copy the setup prompt">
+
+```text
+Help me add Trigger.dev to this project.
+
+## What to do
+
+1. I need a Trigger.dev account. If I don't have one, point me to https://cloud.trigger.dev to sign up. Wait for me to confirm.
+2. Run `npx trigger.dev@latest init` in the project root.
+   - When it asks about the MCP server, recommend I install it (best DX: gives you direct access to Trigger.dev docs, deploys, and run monitoring).
+   - Install the "Hello World" example task when prompted.
+3. Run `npx trigger.dev@latest dev` to start the dev server.
+4. Once the dev server is running, test the example task from the Trigger.dev dashboard.
+5. Set TRIGGER_SECRET_KEY in my .env file (or .env.local for Next.js). I can find it on the API Keys page in the dashboard.
+6. Ask me what framework I'm using and show me how to trigger the task from my backend code.
+
+If I've already run init and want the MCP server, run: npx trigger.dev@latest install-mcp
+
+## Critical rules
+
+- ALWAYS import from `@trigger.dev/sdk`. NEVER import from `@trigger.dev/sdk/v3`.
+- NEVER use `client.defineJob()` — that's the deprecated v2 API.
+- Use type-only imports when triggering from backend code to avoid bundling task code:
+
+  import type { myTask } from "./trigger/example";
+  import { tasks } from "@trigger.dev/sdk";
+
+  const handle = await tasks.trigger<typeof myTask>("my-task-id", { payload: "data" });
+
+## When done, point me to
+
+- Writing tasks: https://trigger.dev/docs/tasks/overview
+- Real-time updates: https://trigger.dev/docs/realtime/overview
+- AI tooling: https://trigger.dev/docs/building-with-ai
+```
+
+</Accordion>
+
+## Manual setup
 
 <Steps titleSize="h3">
 
@@ -26,20 +68,30 @@ Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/open-
 
 </Steps>
 
+## Triggering tasks from your app
+
+The test page in the dashboard is great for verifying your task works. To trigger tasks from your own code, you'll need to set the `TRIGGER_SECRET_KEY` environment variable. Grab it from the API Keys page in the dashboard and add it to your `.env` file.
+
+```bash .env
+TRIGGER_SECRET_KEY=tr_dev_...
+```
+
+See [Triggering](/triggering) for the full guide, or jump straight to framework-specific setup for [Next.js](/guides/frameworks/nextjs), [Remix](/guides/frameworks/remix), or [Node.js](/guides/frameworks/nodejs).
+
 ## Next steps
 
 <CardGroup cols={2}>
 <Card title="Building with AI" icon="brain" href="/building-with-ai">
-  Learn how to build Trigger.dev projects using AI coding assistants
+  Build Trigger.dev projects using AI coding assistants
 </Card>
   <Card title="How to trigger your tasks" icon="bolt" href="/triggering">
-    Learn how to trigger tasks from your code.
+    Trigger tasks from your backend code
   </Card>
   <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview">
-    Tasks are the core of Trigger.dev. Learn what they are and how to write them.
+    Task options, lifecycle hooks, retries, and queues
   </Card>
   <Card title="Guides and example projects" icon="books" href="/guides/introduction">
-  Guides and examples for triggering tasks from your code.
+  Framework guides and working example repos
 </Card>
 
 </CardGroup>
diff --git a/docs/realtime/auth.mdx b/docs/realtime/auth.mdx
@@ -141,6 +141,10 @@ By default, auto-generated tokens expire after 15 minutes and have a read scope
 
 See our [triggering documentation](/triggering) for detailed examples of how to trigger tasks and get auto-generated tokens.
 
+<Note>
+**Where should I create tokens?** The standard pattern is to create tokens in your backend code (API route, server action) after triggering a task, then pass the token to your frontend. The `handle.publicAccessToken` returned by `tasks.trigger()` already does this for you. You rarely need to create tokens inside a task itself.
+</Note>
+
 ### Subscribing to runs with Public Access Tokens
 
 Once you have a Public Access Token, you can use it to authenticate requests to the Realtime API in both backend and frontend applications.

diff --git a/docs/realtime/backend/overview.mdx b/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 |
+|---|---|---|
+| **Run updates** | Subscribe to run status, metadata, and tag changes | [Run updates](/realtime/backend/subscribe) |
+| **Streaming** | 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

diff --git a/docs/realtime/backend/streams.mdx b/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

diff --git a/docs/realtime/backend/subscribe.mdx b/docs/realtime/backend/subscribe.mdx
@@ -1,10 +1,10 @@
 ---
-title: Subscribe functions
-sidebarTitle: Subscribe
-description: Subscribe to run updates using async iterators
+title: "Run updates (backend)"
+sidebarTitle: "Run updates"
+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
 

diff --git a/docs/realtime/how-it-works.mdx b/docs/realtime/how-it-works.mdx
@@ -1,12 +1,14 @@
 ---
-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."
 ---
 
+This page covers the infrastructure behind **run updates** (status, metadata, tags). [Streaming](/tasks/streams) uses a separate transport.
+
 ## Architecture
 
-The Realtime API is built on top of [Electric SQL](https://electric-sql.com/), an open-source PostgreSQL syncing engine. The Trigger.dev API wraps Electric SQL and provides a simple API to subscribe to [runs](/runs) and get real-time updates.
+The run updates system is built on top of [Electric SQL](https://electric-sql.com/), an open-source PostgreSQL syncing engine. The Trigger.dev API wraps Electric SQL and provides a simple API to subscribe to [runs](/runs) and get updates as they happen.
 
 ## Run changes
 

diff --git a/docs/realtime/overview.mdx b/docs/realtime/overview.mdx
@@ -1,39 +1,63 @@
 ---
 title: Realtime overview
 sidebarTitle: Overview
-description: Using the Trigger.dev Realtime API to trigger and/or subscribe to runs in real-time.
+description: "Get live run updates and stream data from background tasks to your frontend or backend. No polling."
 ---
 
-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 is the umbrella for everything live in Trigger.dev.** It covers two things: getting notified when a run's state changes, and streaming continuous data (like AI tokens) from a running task to your app.
 
-You can subscribe to real-time updates for different scopes of runs:
+Both use the same `@trigger.dev/react-hooks` package and the same authentication system. The difference is what they give you.
 
-- **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)
+## Run updates vs Streaming
 
-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:
+| | Run updates | Streaming |
+|---|---|---|
+| **What you get** | Run state: status, metadata, tags | Continuous data you define (AI tokens, file chunks, progress) |
+| **When it fires** | On state changes | While the task runs, as data is produced |
+| **Use case** | Progress bars, status badges, dashboards | AI chat output, live logs, file processing |
+| **React hook** | [`useRealtimeRun`](/realtime/react-hooks/subscribe) | [`useRealtimeStream`](/realtime/react-hooks/streams) |
+| **Setup in task code?** | No, automatic | Yes, using `streams.define()` |
+| **Infrastructure** | [Electric SQL](/realtime/how-it-works) (PostgreSQL sync) | Streams transport |
 
-- **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 (to show a progress bar) while also streaming AI output (to display tokens as they arrive).
 
-## Using Realtime in your applications
+## Run updates
 
-### Authentication
+Subscribe to a run and your code gets called whenever its status, [metadata](/runs/metadata), or [tags](/tags) change. No setup needed in your task code.
 
-All Realtime subscriptions require authentication so you can securely trigger and subscribe to runs. See our [authentication guide](/realtime/auth) for more details.
+You can subscribe to:
 
-### Frontend implementation
+- **Specific runs** by run ID
+- **Runs with specific tags** (e.g., all runs tagged with `user:123`)
+- **Batch runs** within a specific batch
+- **Trigger + subscribe combos** that trigger a task and immediately subscribe (frontend only)
 
-Use our React hooks to build real-time UIs that update as runs execute. Ideal for progress bars, status indicators, and live dashboards.
+→ [React hooks](/realtime/react-hooks/subscribe) | [Backend](/realtime/backend/subscribe)
 
-→ **[See our React hooks guide](/realtime/react-hooks/)**
+## Streaming
 
-### Backend implementation
+Define typed streams in your task, pipe data to them, and read that data from your frontend or backend as it's produced. You need to set up streams in your task code using `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.
+→ [How to emit streams from tasks](/tasks/streams) | [React hooks](/realtime/react-hooks/streams) | [Backend](/realtime/backend/streams)
 
-→ **[See our Backend guide](/realtime/backend)**
+## Authentication
+
+All Realtime hooks and functions require authentication. See the [authentication guide](/realtime/auth) for setup.
+
+## Frequently asked questions
+
+### How do I show a progress bar for a background task?
+
+Use [run metadata](/runs/metadata) to store progress data (like a percentage), then subscribe to the run with [`useRealtimeRun`](/realtime/react-hooks/subscribe). Your component re-renders on every metadata update.
+
+### How do I stream AI/LLM responses from a background task?
+
+Define a stream in your task with `streams.define()`, pipe your AI SDK response to it, then consume it in React with [`useRealtimeStream`](/realtime/react-hooks/streams). See [Streaming data from tasks](/tasks/streams) for the full guide.
+
+### Do I need WebSockets or polling?
+
+No. Run updates are powered by [Electric SQL](/realtime/how-it-works) (HTTP-based PostgreSQL syncing). Streams use their own transport. The hooks handle connections automatically.
+
+### Can I use both run updates and streaming together?
+
+Yes. A common pattern: subscribe to run status with `useRealtimeRun` (progress indicator) while streaming AI output with `useRealtimeStream` (token-by-token display).