docs: Fixes and realtime improvements (#3265)

Author: D-K-P

.cursor/rules/writing-tasks.mdc

@@ -14,7 +14,7 @@ alwaysApply: false
 
 ## Essential requirements when generating task code
 
-1. You MUST use `@trigger.dev/sdk/v3`
+1. You MUST import from `@trigger.dev/sdk` (NEVER `@trigger.dev/sdk/v3`)
 2. You MUST NEVER use `client.defineJob`
 3. YOU MUST `export` every task, including subtasks
 4. If you are able to generate an example payload for a task, do so.
@@ -53,7 +53,7 @@ Instead, you MUST ALWAYS generate ONLY this pattern:
 ```ts
 // ✅ ALWAYS GENERATE THIS EXACT PATTERN
 
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 
 //1. You need to export each task, even if it's a subtask
 export const helloWorld = task({
@@ -71,7 +71,7 @@ export const helloWorld = task({
 A task is a function that can run for a long time with resilience to failure:
 
 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 
 export const helloWorld = task({
   id: "hello-world",
@@ -271,7 +271,7 @@ Global lifecycle hooks can also be defined in `trigger.config.ts` to apply to al
 ## Correct Schedules task (cron) implementations
 
 ```ts
-import { schedules } from "@trigger.dev/sdk/v3";
+import { schedules } from "@trigger.dev/sdk";
 
 export const firstScheduledTask = schedules.task({
   id: "first-scheduled-task",
@@ -312,7 +312,7 @@ export const firstScheduledTask = schedules.task({
 ### Attach a Declarative schedule
 
 ```ts
-import { schedules } from "@trigger.dev/sdk/v3";
+import { schedules } from "@trigger.dev/sdk";
 
 // Sepcify a cron pattern (UTC)
 export const firstScheduledTask = schedules.task({
@@ -326,7 +326,7 @@ export const firstScheduledTask = schedules.task({
 ```
 
 ```ts
-import { schedules } from "@trigger.dev/sdk/v3";
+import { schedules } from "@trigger.dev/sdk";
 
 // Specify a specific timezone like this:
 export const secondScheduledTask = schedules.task({
@@ -375,7 +375,7 @@ const createdSchedule = await schedules.create({
 Schema tasks validate payloads against a schema before execution:
 
 ```ts
-import { schemaTask } from "@trigger.dev/sdk/v3";
+import { schemaTask } from "@trigger.dev/sdk";
 import { z } from "zod";
 
 const myTask = schemaTask({
@@ -400,7 +400,7 @@ When you trigger a task from your backend code, you need to set the `TRIGGER_SEC
 Triggers a single run of a task with specified payload and options without importing the task. Use type-only imports for full type checking.
 
 ```ts
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import type { emailSequence } from "~/trigger/emails";
 
 export async function POST(request: Request) {
@@ -418,7 +418,7 @@ export async function POST(request: Request) {
 Triggers multiple runs of a single task with different payloads without importing the task.
 
 ```ts
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import type { emailSequence } from "~/trigger/emails";
 
 export async function POST(request: Request) {
@@ -436,7 +436,7 @@ export async function POST(request: Request) {
 Triggers multiple runs of different tasks at once, useful when you need to execute multiple tasks simultaneously.
 
 ```ts
-import { batch } from "@trigger.dev/sdk/v3";
+import { batch } from "@trigger.dev/sdk";
 import type { myTask1, myTask2 } from "~/trigger/myTasks";
 
 export async function POST(request: Request) {
@@ -621,7 +621,7 @@ const handle = await myTask.trigger(
 Access metadata inside a run:
 
 ```ts
-import { task, metadata } from "@trigger.dev/sdk/v3";
+import { task, metadata } from "@trigger.dev/sdk";
 
 export const myTask = task({
   id: "my-task",
@@ -713,7 +713,7 @@ Trigger.dev Realtime enables subscribing to runs for real-time updates on run st
 Subscribe to a run after triggering a task:
 
 ```ts
-import { runs, tasks } from "@trigger.dev/sdk/v3";
+import { runs, tasks } from "@trigger.dev/sdk";
 
 async function myBackend() {
   const handle = await tasks.trigger("my-task", { some: "data" });
@@ -735,7 +735,7 @@ async function myBackend() {
 You can infer types of run's payload and output by passing the task type:
 
 ```ts
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";
 import type { myTask } from "./trigger/my-task";
 
 for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
@@ -752,7 +752,7 @@ for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
 Stream data in realtime from inside your tasks using the metadata system:
 
 ```ts
-import { task, metadata } from "@trigger.dev/sdk/v3";
+import { task, metadata } from "@trigger.dev/sdk";
 import OpenAI from "openai";
 
 export type STREAMS = {
@@ -947,7 +947,7 @@ For most use cases, Realtime hooks are preferred over SWR hooks with polling due
 For client-side usage, generate a public access token with appropriate scopes:
 
 ```ts
-import { auth } from "@trigger.dev/sdk/v3";
+import { auth } from "@trigger.dev/sdk";
 
 const publicToken = await auth.createPublicToken({
   scopes: {
@@ -967,7 +967,7 @@ Idempotency ensures that an operation produces the same result when called multi
 Provide an `idempotencyKey` when triggering a task to ensure it runs only once with that key:
 
 ```ts
-import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
 
 export const myTask = task({
   id: "my-task",
@@ -1058,7 +1058,7 @@ function hash(payload: any): string {
 
 ```ts
 // onFailure executes after all retries are exhausted; use for notifications, logging, or side effects on final failure:
-import { task, logger } from "@trigger.dev/sdk/v3";
+import { task, logger } from "@trigger.dev/sdk";
 
 export const loggingExample = task({
   id: "logging-example",
@@ -1078,7 +1078,7 @@ export const loggingExample = task({
 The `trigger.config.ts` file configures your Trigger.dev project, specifying task locations, retry settings, telemetry, and build options.
 
 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 
 export default defineConfig({
   project: "<project ref>",
@@ -1226,7 +1226,7 @@ await myTask.trigger({ name: "Alice", age: 30 });
 
 Before generating any code, you MUST verify:
 
-1. Are you importing from `@trigger.dev/sdk/v3`? If not, STOP and FIX.
+1. Are you importing from `@trigger.dev/sdk` (NOT `@trigger.dev/sdk/v3`)? If not, STOP and FIX.
 2. Have you exported every task? If not, STOP and FIX.
 3. Have you generated any DEPRECATED code patterns? If yes, STOP and FIX.
 

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"

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).

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 />

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

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>("hello-world", { message: "Hello from my app!" });
+
+## 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>

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.

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