Updated the structure

Author: D-K-P

docs/docs.json

@@ -123,7 +123,7 @@
                 "pages": [
                   "realtime/react-hooks/overview",
                   "realtime/react-hooks/triggering",
-                  "realtime/react-hooks/realtime",
+                  "realtime/react-hooks/subscribe",
                   "realtime/react-hooks/streams",
                   "realtime/react-hooks/swr"
                 ]

docs/realtime/auth.mdx

@@ -1,12 +1,23 @@
 ---
 title: Realtime authentication
-sidebarTitle: Realtime authentication
-description: Authenticating real-time API requests with Public Access Tokens
+sidebarTitle: Realtime auth
+description: Authenticating real-time API requests with Public Access Tokens or Trigger Tokens
 ---
 
-To use the Realtime API, you need to authenticate your requests with Public Access Tokens. These tokens provide secure, scoped access to your runs and can be used in both frontend and backend applications.
+To use the Realtime API, you need to authenticate your requests with Public Access Tokens or Trigger Tokens. These tokens provide secure, scoped access to your runs and can be used in both frontend and backend applications.
 
-## Creating Public Access Tokens
+## Token Types
+
+There are two types of tokens you can use with the Realtime API:
+
+- **[Public Access Tokens](#public-access-tokens-for-subscribing-to-runs)** - Used to read and subscribe to run data. Can be used in both frontend and backend applications.
+- **[Trigger Tokens](#trigger-tokens-for-frontend-triggering-only)** - Used to trigger tasks from your frontend. These are more secure, single-use tokens that can only be used in frontend applications.
+
+## Public Access Tokens (for subscribing to runs)
+
+Public Access Tokens are used to read and subscribe to run data. They can be used in both frontend and backend applications to subscribe to runs.
+
+### Creating Public Access Tokens
 
 You can create a Public Access Token using the `auth.createPublicToken` function in your **backend** code:
 
@@ -16,7 +27,7 @@ import { auth } from "@trigger.dev/sdk/v3";
 const publicToken = await auth.createPublicToken(); // 👈 this public access token has no permissions, so is pretty useless!
 ```
 
-## Scopes
+### Scopes
 
 By default a Public Access Token has no permissions. You must specify the scopes you need when creating a Public Access Token:
 
@@ -103,7 +114,7 @@ const publicToken = await auth.createPublicToken({
 });
 ```
 
-## Expiration
+### Expiration
 
 By default, Public Access Token's expire after 15 minutes. You can specify a different expiration time when creating a Public Access Token:
 
@@ -121,72 +132,36 @@ const publicToken = await auth.createPublicToken({
 
 The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.
 
-## Auto-generated tokens
+### Auto-generated tokens
 
-When triggering a task from your backend, the `handle` received from the `trigger` function now includes a `publicAccessToken` field. This token can be used to authenticate requests in your frontend application:
+When you [trigger tasks](/triggering) from your backend, the `handle` received includes a `publicAccessToken` field. This token can be used to authenticate real-time requests in your frontend application.
 
-```ts
-import { tasks } from "@trigger.dev/sdk/v3";
+By default, auto-generated tokens expire after 15 minutes and have a read scope for the specific run(s) that were triggered. You can customize the expiration by passing a `publicTokenOptions` object to the trigger function.
 
-const handle = await tasks.trigger("my-task", { some: "data" });
+See our [triggering documentation](/triggering) for detailed examples of how to trigger tasks and get auto-generated tokens.
 
-console.log(handle.publicAccessToken);
-```
+### Subscribing to runs with Public Access Tokens
 
-By default, tokens returned from the `trigger` function expire after 15 minutes and have a read scope for that specific run. You can customize the expiration of the auto-generated tokens by passing a `publicTokenOptions` object to the `trigger` function:
+Once you have a Public Access Token, you can use it to authenticate requests to the Realtime API in both backend and frontend applications.
 
-```ts
-import { tasks } from "@trigger.dev/sdk/v3";
+**Backend usage:** See our [backend subscription documentation](/realtime/backend/subscribe) for examples of using tokens with backend functions.
 
-const handle = await tasks.trigger(
-  "my-task",
-  { some: "data" },
-  {
-    tags: ["my-tag"],
-  },
-  {
-    publicAccessToken: {
-      expirationTime: "1hr",
-    },
-  }
-);
-```
+**Frontend usage:** See our [React hooks documentation](/realtime/react-hooks) for examples of using tokens with frontend components.
 
-You will also get back a Public Access Token when using the `batchTrigger` function:
-
-```ts
-import { tasks } from "@trigger.dev/sdk/v3";
-
-const handle = await tasks.batchTrigger("my-task", [
-  { payload: { some: "data" } },
-  { payload: { some: "data" } },
-  { payload: { some: "data" } },
-]);
-
-console.log(handle.publicAccessToken);
-```
-
-## Trigger tokens
+## Trigger Tokens (for frontend triggering only)
 
 For triggering tasks from your frontend, you need special "trigger" tokens. These tokens can only be used once to trigger a task and are more secure than regular Public Access Tokens.
 
+### Creating Trigger Tokens
+
 ```ts
 import { auth } from "@trigger.dev/sdk/v3";
 
 // Somewhere in your backend code
 const triggerToken = await auth.createTriggerPublicToken("my-task");
 ```
 
-These tokens also expire, with the default expiration time being 15 minutes. You can specify a custom expiration time:
-
-```ts
-import { auth } from "@trigger.dev/sdk/v3";
-
-// Somewhere in your backend code
-const triggerToken = await auth.createTriggerPublicToken("my-task", {
-  expirationTime: "24hr",
-});
-```
+### Multiple tasks
 
 You can pass multiple tasks to create a token that can trigger multiple tasks:
 
@@ -197,6 +172,8 @@ import { auth } from "@trigger.dev/sdk/v3";
 const triggerToken = await auth.createTriggerPublicToken(["my-task-1", "my-task-2"]);
 ```
 
+### Multiple use
+
 You can also create tokens that can be used multiple times:
 
 ```ts
@@ -208,36 +185,21 @@ const triggerToken = await auth.createTriggerPublicToken("my-task", {
 });
 ```
 
-## Using tokens
+### Expiration
 
-Once you have a Public Access Token, you can use it to authenticate requests to the Realtime API:
-
-### Backend usage
+These tokens also expire, with the default expiration time being 15 minutes. You can specify a custom expiration time:
 
 ```ts
-import { runs } from "@trigger.dev/sdk/v3";
-
-// Using the token with backend functions
-for await (const run of runs.subscribeToRun("run_1234", {
-  accessToken: publicToken,
-})) {
-  console.log(run);
-}
-```
-
-### Frontend usage
+import { auth } from "@trigger.dev/sdk/v3";
 
-```tsx
-import { useRealtimeRun } from "@trigger.dev/react-hooks";
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  expirationTime: "24hr",
+});
+```
 
-export function MyComponent({ runId, publicAccessToken }) {
-  const { run, error } = useRealtimeRun(runId, {
-    accessToken: publicAccessToken,
-  });
+### Triggering tasks from frontend with Trigger Tokens
 
-  if (error) return <div>Error: {error.message}</div>;
-  return <div>Run: {run?.id}</div>;
-}
-```
+To trigger tasks from your frontend, you need to use special Trigger Tokens created in your backend. See our [React hooks triggering documentation](/realtime/react-hooks/triggering) for complete examples.
 
 See our [React hooks documentation](/realtime/react-hooks) for more details on using hooks in your frontend application.

docs/realtime/overview.mdx

@@ -6,9 +6,18 @@ description: Using the Trigger.dev Realtime API to subscribe to runs in real-tim
 
 import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
 
-Trigger.dev Realtime allows you subscribe to runs and get real-time updates as they execute. This is useful for monitoring runs, updating UIs, and building real-time dashboards.
+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.
 
-## What you can subscribe to
+## Authentication
+
+All Realtime subscriptions require authentication so you can securely trigger and subscribe to runs. See our [authentication guide](/realtime/auth) for details on:
+
+- Creating Public Access Tokens to subscribe to runs
+- Creating Trigger Tokens to trigger tasks from your frontend
+- Scoping tokens to specific runs, tasks, tags, or batches
+- Auto-generated tokens from `tasks.trigger()`
+
+## How run subscriptions work
 
 You can subscribe to real-time updates for:
 
@@ -17,7 +26,7 @@ You can subscribe to real-time updates for:
 - **Task runs** - All runs for specific tasks
 - **Batch runs** - All runs in a batch
 
-You automatically receive the complete [run object](/realtime/run-object) containing status, timestamps, metadata, tags, and more whenever:
+When you subscribe to runs, you automatically receive the complete [run object](/realtime/run-object) containing status, timestamps, metadata, tags, and more whenever:
 
 - Run status changes (queued → executing → completed, etc.)
 - [Run metadata](/runs/metadata) is updated
@@ -29,23 +38,15 @@ Your tasks can also send additional custom data:
 - **Metadata updates** - Update custom metadata on runs that gets streamed to subscribers ([backend](/realtime/backend/metadata) | [React hooks](/realtime/react-hooks/realtime#using-metadata))
 - **Stream function** - Stream data chunks in real-time, perfect for AI/LLM streaming ([backend](/realtime/backend/streams) | [React hooks](/realtime/react-hooks/streams))
 
-## Authentication
-
-All Realtime subscriptions require authentication. See our [authentication guide](/realtime/auth) for details on:
-
-- Creating Public Access Tokens for frontend use
-- Scoping tokens to specific runs, tasks, tags, or batches
-- Auto-generated tokens from `tasks.trigger()`
-
 ## Implementation approaches
 
-### Backend subscriptions
+### Backend implementation
 
 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.
 
 → **[See Backend functions guide](/realtime/backend)**
 
-### Frontend subscriptions
+### Frontend implementation
 
 Use our React hooks to build real-time UIs that update as runs execute. Ideal for progress bars, status indicators, and live dashboards.
 

docs/realtime/react-hooks/realtime.mdx docs/realtime/react-hooks/subscribe.mdxdocs/realtime/react-hooks/realtime.mdx renamed to docs/realtime/react-hooks/subscribe.mdx

@@ -1,6 +1,6 @@
 ---
-title: Realtime hooks
-sidebarTitle: Realtime
+title: Subscribing to runs
+sidebarTitle: Subscribe
 description: Get live updates from runs, batches, metadata, and more in your frontend application.
 ---
 

docs/realtime/react-hooks/triggering.mdx

@@ -8,9 +8,12 @@ import RealtimeExamplesCards from "/snippets/realtime-examples-cards.mdx";
 
 We provide a set of hooks that can be used to trigger tasks from your frontend application.
 
-## Demo
-
-We've created a [Demo application](https://github.com/triggerdotdev/realtime-llm-battle) that demonstrates how to use our React hooks to trigger tasks in a Next.js application. The application uses the `@trigger.dev/react-hooks` package to trigger a task and subscribe to the run in real-time.
+<Note>
+  For triggering tasks from your frontend, you need to use “trigger” tokens. These can only be used
+  once to trigger a task and are more secure than regular Public Access Tokens. To learn more about
+  how to create and use these tokens, see our [Trigger Tokens](/realtime/auth#trigger-tokens)
+  documentation.
+</Note>
 
 ## Hooks