@trigger.dev/sdk 4.5.16 → 4.6.0

package/docs/introduction.mdx

@@ -1,181 +1,69 @@
 ---
-title: "Welcome to the Trigger.dev docs"
+title: "Trigger.dev docs"
 sidebarTitle: "Introduction"
-description: "Find all the resources and guides you need to get started"
+description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, observability, and elastic scaling. Open source and self-hostable."
 mode: "center"
 ---
 
 <CardGroup cols={2}>
-  <Card title="Quick start" img="/images/intro-quickstart.jpg" href="/quick-start">
-    Get started with Trigger.dev and run your first task in 3 minutes
+  <Card title="Quick start" icon="rocket" href="/quick-start" color="#A8FF53">
+    Go from zero to your first task in 3 minutes.
   </Card>
-  <Card
-    title="Guides, frameworks & examples"
-    img="/images/intro-examples.jpg"
-    href="/guides/introduction#example-tasks"
-  >
-    Browse our wide range of guides, frameworks and example projects
+  <Card title="Build AI agents" icon="robot" href="/guides/ai-agents/overview" color="#a855f7">
+    Agent patterns, worked examples, and the tools to run them in production.
   </Card>
-  <Card title="Building with AI" img="/images/intro-ai.jpg" href="/building-with-ai">
-    Learn how to build Trigger.dev projects using AI coding assistants
+  <Card title="AI coding assistants" icon="wand-magic-sparkles" href="/building-with-ai" color="#3B82F6">
+    Let Claude Code, Cursor and Windsurf write correct Trigger.dev code with the MCP server, Skills and rules.
   </Card>
-  <Card title="Video walkthrough" img="/images/intro-video.jpg" href="/video-walkthrough">
-    Watch an end-to-end demo of Trigger.dev in 10 minutes
+  <Card title="Guides & examples" icon="book-open" href="/guides/introduction" color="#f6cd46">
+    Frameworks like Next.js, worked example projects, and step-by-step how-to guides.
   </Card>
 </CardGroup>
 
 ## What is Trigger.dev?
 
-Trigger.dev is an open source background jobs framework that lets you write reliable workflows in plain async code. Run long-running AI tasks, handle complex background jobs, and build AI agents with built-in queuing, automatic retries, and real-time monitoring. No timeouts, elastic scaling, and zero infrastructure management required.
+Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. Run them for hours, configure automatic retries, control concurrency, and manage queues. There's no execution timeout, and no queue or worker infrastructure for you to build.
+
+You write agents and tasks in your existing codebase using our CLI and SDK, and get durable execution, queues, waits, full tracing, and elastic scaling without building any of it yourself.
 
-We provide everything you need to build and manage background tasks: a CLI and SDK for writing tasks in your existing codebase, support for both [regular](/tasks/overview) and [scheduled](/tasks/scheduled) tasks, full observability through our dashboard, and a [Realtime API](/realtime) with [React hooks](/realtime/react-hooks#realtime-hooks) for showing task status in your frontend. You can use [Trigger.dev Cloud](https://cloud.trigger.dev) or [self-host](/self-hosting/overview) on your own infrastructure.
+Trigger.dev's core is Apache-2.0 licensed, a genuine OSI license. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
 
-## Learn the concepts
+## Core concepts
 
 <CardGroup cols={2}>
-  <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview" color="#3B82F6">
-    Tasks are the core of Trigger.dev. Learn what they are and how to write them.
+  <Card title="Writing tasks" icon="pen-to-square" href="/tasks/overview" color="#A8FF53">
+    The durable functions at the core of Trigger.dev. Write them in your existing codebase, with retries and no timeouts.
   </Card>
-  <Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#fbbf24">
-    Learn how to trigger tasks from your codebase.
+  <Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#3b82f6">
+    Trigger a task from your backend, your frontend, a schedule, or another task.
   </Card>
-  <Card title="Runs" icon="person-running" href="/runs" color="#EA189E">
-    Runs are the instances of tasks that are executed. Learn how they work.
+  <Card title="Runs" icon="play" href="/runs" color="#28bf5c">
+    Every execution of a task is a run, with its status, retries, and logs recorded.
   </Card>
-  <Card title="API keys" icon="key" href="/apikeys" color="#EAEA08">
-    API keys are used to authenticate requests to the Trigger.dev API. Learn how to create and use
-    them.
+  <Card title="Idempotency" icon="fingerprint" href="/idempotency" color="#F43F5E">
+    Use an idempotency key so a retried or duplicated trigger runs once, not twice.
   </Card>
 </CardGroup>
 
-## Explore by feature
+## Build with agents
 
-<CardGroup>
-  <Card title="Scheduled tasks (cron)" icon="clock" href="/tasks/scheduled" color="#EAEA08">
-    Scheduled tasks are a type of task that is scheduled to run at a specific time.
-  </Card>
-  <Card title="Realtime API" icon="loader" href="/realtime" color="#22C55E">
-    The Realtime API allows you to trigger tasks and get the status of runs.
-  </Card>
-  <Card title="React hooks" icon="react" href="/realtime/react-hooks" color="#3B82F6">
-    React hooks are a way to show task status in your frontend.
-  </Card>
-  <Card title="Waits" icon="calendar-clock" href="/wait" color="#F59E0B">
-    Waits are a way to wait for a task to finish before continuing.
-  </Card>
-  <Card
-    title="Errors and retries"
-    icon="message-exclamation"
-    href="/errors-retrying"
-    color="#F43F5E"
-  >
-    Learn how to handle errors and retries.
-  </Card>
-  <Card title="Concurrency & Queues" icon="line-height" href="/queue-concurrency" color="#D946EF">
-    Configure what you want to happen when there is more than one run at a time.
-  </Card>
-  <Card
-    title="Wait for token (human-in-the-loop)"
-    icon="hand"
-    href="/wait-for-token"
-    color="#EAEA08"
-  >
-    Pause runs until a token is completed via an approval workflow.
-  </Card>
-  <Card title="Build extensions" icon="gear" href="/config/extensions/overview" color="#22C55E">
-    Customize the build process or the resulting bundle and container image.
-  </Card>
-</CardGroup>
+Build durable, multi-turn agents with the [chat agent](/ai-chat/overview): one long-running task per conversation, with the tools it can call, streaming, and resumability handled for you. Add human-in-the-loop approval by pausing a run on a [waitpoint](/wait-for-token) until a person signs off, and a waiting run doesn't consume compute. Stream run status and LLM output straight to your frontend with the [Realtime API](/realtime/overview) and React hooks, and record your Vercel AI SDK calls as spans with the model, token counts, cost and latency using [AI observability](/ai/observability). Version your [prompts](/ai/prompts) in code, then edit the text or swap the model from the dashboard without redeploying.
 
-## Explore by build extension
-
-| Extension             | What it does                                                 | Docs                                                   |
-| :-------------------- | :----------------------------------------------------------- | :----------------------------------------------------- |
-| prismaExtension       | Use Prisma with Trigger.dev                                  | [prismaExtension docs](/config/extensions/prismaExtension)             |
-| pythonExtension       | Execute Python scripts in Trigger.dev                        | [pythonExtension docs](/config/extensions/pythonExtension)             |
-| playwright            | Use Playwright with Trigger.dev                              | [playwright extension docs](/config/extensions/playwright)             |
-| puppeteer             | Use Puppeteer with Trigger.dev                               | [puppeteer extension docs](/config/extensions/puppeteer)               |
-| lightpanda            | Use Lightpanda with Trigger.dev                              | [lightpanda extension docs](/config/extensions/lightpanda)             |
-| ffmpeg                | Use FFmpeg with Trigger.dev                                  | [ffmpeg extension docs](/config/extensions/ffmpeg)                     |
-| aptGet                | Install system packages with aptGet                          | [aptGet extension docs](/config/extensions/aptGet)                     |
-| additionalFiles       | Copy additional files to the build directory                 | [additionalFiles docs](/config/extensions/additionalFiles)             |
-| additionalPackages    | Include additional packages in the build                     | [additionalPackages docs](/config/extensions/additionalPackages)       |
-| syncEnvVars           | Automatically sync environment variables to Trigger.dev      | [syncEnvVars docs](/config/extensions/syncEnvVars)                     |
-| esbuildPlugin         | Add existing or custom esbuild plugins to your build process | [esbuildPlugin docs](/config/extensions/esbuildPlugin)                 |
-| emitDecoratorMetadata | Support for the emitDecoratorMetadata TypeScript compiler    | [emitDecoratorMetadata docs](/config/extensions/emitDecoratorMetadata) |
-| audioWaveform         | Support for Audio Waveform in your project                   | [audioWaveform docs](/config/extensions/audioWaveform)                 |
-
-## Explore by example
-
-<CardGroup cols={3}>
-  <Card
-    title="FFmpeg"
-    img="/images/intro-ffmpeg.jpg"
-    href="/guides/examples/ffmpeg-video-processing"
-  />
-  <Card
-    title="Fal.ai"
-    img="/images/intro-fal.jpg"
-    href="/guides/examples/fal-ai-image-to-cartoon"
-  />
-  <Card title="Puppeteer" img="/images/intro-puppeteer.jpg" href="/guides/examples/puppeteer" />
-  <Card
-    title="LibreOffice"
-    img="/images/intro-libreoffice.jpg"
-    href="/guides/examples/libreoffice-pdf-conversion"
-  />
-  <Card
-    title="OpenAI"
-    img="/images/intro-openai.jpg"
-    href="/guides/examples/open-ai-with-retrying"
-  />
-  <Card
-    title="Browserbase"
-    img="/images/intro-browserbase.jpg"
-    href="/guides/examples/scrape-hacker-news"
-  />
-  <Card
-    title="Sentry"
-    img="/images/intro-sentry.jpg"
-    href="/guides/examples/sentry-error-tracking"
-  />
-  <Card
-    title="Resend"
-    img="/images/intro-resend.jpg"
-    href="/guides/examples/resend-email-sequence"
-  />
-  <Card
-    title="Vercel AI SDK"
-    img="/images/intro-vercel.jpg"
-    href="/guides/examples/vercel-ai-sdk"
-  />
-  <Card
-    title="Sharp"
-    img="/images/intro-sharp.jpg"
-    href="/guides/examples/sharp-image-processing"
-  />
-  <Card
-    title="Deepgram"
-    img="/images/intro-deepgram.jpg"
-    href="/guides/examples/deepgram-transcribe-audio"
-  />
-  <Card
-    title="Supabase"
-    img="/images/intro-supabase.jpg"
-    href="/guides/examples/supabase-database-operations"
-  />
-  <Card
-    title="DALL•E"
-    img="/images/intro-openai.jpg"
-    href="/guides/examples/dall-e3-generate-image"
-  />
-  <Card
-    title="Firecrawl"
-    img="/images/intro-firecrawl.jpg"
-    href="/guides/examples/firecrawl-url-crawl"
-  />
-  <Card title="Lightpanda" img="/images/intro-lightpanda.jpg" href="/guides/examples/lightpanda" />
-</CardGroup>
+## Scale and scheduling
+
+Set how many runs of a task execute at once, globally or per tenant, with [queues and concurrency](/queue-concurrency). Run a task on a [cron schedule](/tasks/scheduled) with timezone support, choose the CPU and memory each task runs on with [machines](/machines), and control what happens when a task throws with [errors and retries](/errors-retrying).
+
+## Self-hosting
+
+Trigger.dev is open source and you can self-host. Read the [overview guide](/self-hosting/overview), or how to do it with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
+
+## Frequently asked questions
+
+**How do I add human-in-the-loop approval to an agent?** Pause the run on a [waitpoint](/wait-for-token) until a person approves the action. A waiting run doesn't consume compute, so it can wait minutes or days.
+
+**Does Trigger.dev support tool calling and MCP?** Yes. Agents call the tools you define, and the [MCP server](/building-with-ai) lets AI coding assistants trigger tasks, deploy, and read run traces.
+
+**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
 
 ## Getting help
 
@@ -221,3 +109,21 @@ We'd love to hear from you or give you a hand getting started. Here are some way
     Check us out our GitHub repo and give us a star if you like what we're doing.
   </Card>
 </CardGroup>
+
+<Visibility for="agents">
+
+## Facts for AI assistants
+
+**Current major version:** v4 (`@trigger.dev/sdk` 4.x). Documentation under `/docs/v2` and `/docs/v3` describes superseded versions and should not be used.
+
+**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. A task runs until it finishes; you can cap runtime with `maxDuration` (minimum 5 seconds).
+
+**Deploys:** each deploy is an atomic version. A run already in progress is not affected by code shipped after it started.
+
+**Durability and retries:** retries are automatic and configurable. A failed attempt is retried according to the task's retry settings; once retries are exhausted the run ends terminally as `FAILED`, and some crashes (for example out of memory) end the run as `CRASHED` without a retry. Idempotency keys deduplicate the task triggers and waits you key, so the same key runs once instead of again.
+
+**License:** the platform core is Apache-2.0 and the `@trigger.dev/sdk` package is MIT, permissive open source, not fair-code or source-available. Some features are gated, but the open source core is not relicensed or held back.
+
+**LLM observability coverage:** only Vercel AI SDK calls (`generateText`, `streamText`, `generateObject`) are recorded as spans. Raw `fetch` calls and provider SDKs used directly are not captured.
+
+</Visibility>

package/docs/manual-setup.mdx

@@ -55,15 +55,15 @@ bun add -D @trigger.dev/build@latest
 
 ## Environment variables
 
-For local development, you need to set up the `TRIGGER_SECRET_KEY` environment variable. This key authenticates your application with Trigger.dev.
+For local development, create a named environment API key and set it as `TRIGGER_SECRET_KEY`:
 
-1. Go to your project dashboard in Trigger.dev
-2. Navigate to the "API Keys" page
-3. Copy the **DEV** secret key
-4. Add it to your local environment file:
+1. Open your project's Development environment in the Trigger.dev dashboard.
+2. Open the **API Keys** page.
+3. Click **New API key**, give it a descriptive name, and select **Trigger only** access.
+4. Copy the key and add it to your local environment file. Trigger.dev shows the complete value only once.
 
-```bash
-TRIGGER_SECRET_KEY=tr_dev_xxxxxxxxxx
+```bash .env
+TRIGGER_SECRET_KEY=tr_dev_sk_xxxxxxxxxx
 ```
 
 ### Self-hosted instances

package/docs/mcp-tools.mdx

@@ -189,6 +189,15 @@ Execute a single widget query from a built-in dashboard. Use `list_dashboards` f
 - `"Run the total runs widget from the overview dashboard"`
 - `"Show me the LLM cost over time from the AI dashboard"`
 
+### get_report
+
+Render an interpreted [health report](/reports) — a deterministic verdict, not a raw panel — as text with sparklines. The `health` report answers whether work is flowing, whether the runs that start are healthy, and whether the telemetry is fresh, with a headline verdict and a suggested next action. Returns markdown by default, or ANSI when `color` is set. Read-only.
+
+**Example usage:**
+- `"Is my production project healthy?"`
+- `"Run the health report for the last 24 hours"`
+- `"Why are my runs backing up?"`
+
 ## Dev Server Tools
 
 ### start_dev_server

package/docs/quick-start.mdx

@@ -26,7 +26,7 @@ Help me add Trigger.dev to this project.
    - 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.
+5. Create a named API key in my Development environment with **Trigger only** access. Set it as TRIGGER_SECRET_KEY in my .env file (or .env.local for Next.js).
 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
@@ -70,10 +70,10 @@ Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/self-
 
 ## 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.
+The test page in the dashboard verifies that your task works. To trigger tasks from your own code, open the API Keys page for your Development environment and create a named key with **Trigger only** access. Set the key as `TRIGGER_SECRET_KEY` in your `.env` file.
 
 ```bash .env
-TRIGGER_SECRET_KEY=tr_dev_...
+TRIGGER_SECRET_KEY=tr_dev_sk_...
 ```
 
 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).

package/docs/realtime/auth.mdx

@@ -131,7 +131,7 @@ const publicToken = await auth.createPublicToken({
 - If `expirationTime` is a number, it will be treated as a Unix timestamp in **seconds**
 - If `expirationTime` is a `Date`, it will be treated as a date
 
-When using non-root API keys (recommended), the expiration cannot be more than 30 days in the future.
+Public Access Tokens cannot expire more than 30 days in the future.
 
 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.
 

package/docs/reports.mdx

@@ -0,0 +1,157 @@
+---
+title: "Project health report"
+sidebarTitle: "Health report"
+description: "Get a deterministic verdict on your project's health — split into Flow, Execution, and Liveness — from the CLI, an MCP tool or prompt, or the HTTP API."
+---
+
+**The health report answers one question — "is my project healthy, and if not, is the problem my code or the platform?" — with a deterministic verdict, not a dashboard.** The server computes the verdict from your telemetry; no LLM interprets it, so the same numbers always produce the same answer.
+
+Every report reads a live window of your project's data and returns a headline verdict, the evidence behind it, and a single suggested next action. The only report today is `health`.
+
+## What the report measures
+
+The report splits a project into three dimensions, each with its own verdict:
+
+| Dimension | Question | What a bad verdict means |
+| --- | --- | --- |
+| **Flow** | Is work starting? | Runs are queuing but not being picked up — a concurrency limit, a throttle, or a trigger spike. |
+| **Execution** | Are the runs that start succeeding? | Runs are failing or slowing more than your baseline — usually your code. |
+| **Liveness** | Is the telemetry fresh? | The data behind the report is stale, so the verdict can't be trusted. |
+
+Splitting Flow from Execution is the point: a project can be failing to _start_ work (Flow) while every run that does start _completes_ fine (Execution), or the reverse. The report names which one, so you know whether to look at your concurrency settings or your task code.
+
+Each dimension carries a severity — healthy, degraded, or failing — and the report leads with the worst one as its headline. The headline finding is expanded with its supporting metrics; the others collapse to a one-line verdict.
+
+## Reading the report
+
+Here is `trigger report health` for a project whose runs are backing up against the environment concurrency limit:
+
+```text
+/report health        prod · last 1h · vs 7d normal
+
+✕ Flow stalled — at your env concurrency limit for the last 40 min
+
+  concurrency     100/100           ▄▅▆▇████   40 min at limit
+  pending         1,240      ↑ 6×   ▁▂▄▅▆▇██   (normal ~120)
+  start latency   p95 8.2s   ↑ 4×   ▁▂▃▄▆▇██   (normal ~2s)
+
+  why:  runs are finishing at ~90/min
+        nothing dead-lettered
+
+✓ EXECUTION   runs are executing normally
+
+✓ LIVENESS    fresh — telemetry current, updated 12s ago
+
+  read: limit saturated → incoming work exceeds capacity → backlog grows
+
+→ Raise the env concurrency limit
+  Read concurrency docs
+  or do nothing — backlog drains in ~26.7 min once triggers ease
+```
+
+The verdict reads top to bottom:
+
+- **Headline** — the worst finding, stated as a verdict with the breach window. Here Flow is stalled because concurrency has been pinned at its limit for 40 minutes.
+- **Evidence** — the metrics behind the headline, each with a sparkline over the window, its movement against your baseline (`↑ 6×` means six times normal), and an annotation (`40 min at limit`) or baseline (`normal ~120`).
+- **`why:`** — the facts that support the verdict, including what the problem _isn't_ (runs are still finishing, nothing is dead-lettered — so it's not your code).
+- **Sibling findings** — Execution and Liveness, each a one-line verdict.
+- **`read:`** — the causal chain in one line.
+- **Next steps** — the primary action first (`→`), then any alternatives.
+
+### The verdict vocabulary
+
+Every surface carries meaning in glyphs, never color alone, so the report is legible in a monochrome terminal or a plain-text MCP host:
+
+| Glyph | Meaning |
+| --- | --- |
+| `✓` | Healthy |
+| `⚠` | Degraded |
+| `✕` | Failing |
+| `○` | Genuinely unknown — neither good nor bad |
+| `⚑` | The data behind the report can't be trusted |
+| `↑` `↓` `→` | Above, below, or flat against the baseline |
+
+<Note>
+  The markdown surface swaps the status glyphs for traffic-light emoji (`🟢` `🟡` `🔴` `⚪` `🚩`) — the one color cue a chat host that renders neither ANSI nor HTML can show. The glyph and the emoji mean the same thing.
+</Note>
+
+## Surfaces
+
+The same report renders four ways.
+
+### CLI: `trigger report`
+
+Print an interpreted report for an environment. The command defaults to the `health` report and the `prod` environment — a manual production check.
+
+```bash
+npx trigger.dev@latest report health --env prod --period 24h
+```
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `[key]` | `health` | The report to render (positional argument). |
+| `-e, --env` | `prod` | The environment: `dev`, `staging`, `prod`, or `preview`. |
+| `-b, --branch` | — | The preview branch. Required when `--env preview`. |
+| `--period` | `1h` | The live window: `30m`, `1h`, `24h`, `7d`. Minutes to weeks, max 90 days. |
+| `-p, --project-ref` | from config | The project ref (`proj_…`). Required if there is no `trigger.config.ts`. |
+| `-c, --config` | — | Path to the config file. |
+
+The command prints only the report — no banner — so it pipes cleanly. Output is ANSI-colored in a real terminal and plain markdown when piped:
+
+```bash
+trigger report health > health.md   # markdown, no escape codes
+```
+
+Color follows the [supports-color](https://github.com/chalk/supports-color) convention: `NO_COLOR` (any value) or `FORCE_COLOR=0` disables color outright; `FORCE_COLOR` set to anything else force-enables it. Both win over TTY detection — which matters for agents spawned on a PTY, where `isTTY` is `true` but escape codes would be garbled.
+
+### MCP tool: `get_report`
+
+Fetch the report from an AI coding tool through the [Trigger.dev MCP server](/mcp-introduction). The tool returns plain markdown by default, or ANSI when `color` is set (for hosts that display escapes in tool output). It is read-only.
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `key` | — | The report to render. Currently only `health`. |
+| `environment` | `dev` | The environment. The MCP server is dev-centric, so an unspecified environment reports on `dev` — pass `environment` explicitly to report on production. |
+| `period` | `1h` | Time window shorthand, e.g. `1h`, `24h`, `7d`. |
+| `color` | `false` | Return ANSI-colored text instead of markdown. |
+| `projectRef` | auto-detected | The project ref. Detected from `trigger.config.ts` if present. |
+| `branch` | — | The preview branch, for preview or branchable dev environments. |
+
+### MCP prompt: `/report`
+
+The MCP server also registers a `report` prompt, which hosts that support MCP prompts surface as a slash command (Claude Code renders it as `/mcp__trigger__report`). Running `/report health` calls `get_report` for you and shows the result verbatim in a fenced code block, preserving the monospace alignment and sparklines.
+
+### HTTP API: `GET /api/v1/reports/:key`
+
+The endpoint behind every surface. It accepts a `period` and a `format`, and authenticates with a token scoped to read the report's query tables (`read:query`).
+
+| Query param | Default | Description |
+| --- | --- | --- |
+| `period` | `1h` | The live window, same grammar as the CLI. |
+| `format` | `markdown` | `markdown`, `ansi`, or `json`. |
+
+`format=markdown` and `format=ansi` return the rendered text. `format=json` returns the `ReportViewModel` — the semantic payload behind the render, where verdicts are codes rather than prose, for building your own surface on top of the report.
+
+```bash
+curl "https://api.trigger.dev/api/v1/reports/health?period=24h&format=json" \
+  -H "Authorization: Bearer $TRIGGER_ACCESS_TOKEN"
+```
+
+An unknown report key returns `404` with the list of available keys.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="MCP server" icon="plug" href="/mcp-introduction">
+    Connect your AI coding tool to Trigger.dev.
+  </Card>
+  <Card title="MCP tools" icon="wrench" href="/mcp-tools">
+    Every tool the MCP server exposes, including `get_report`.
+  </Card>
+  <Card title="Concurrency & queues" icon="layer-group" href="/queue-concurrency">
+    Configure the concurrency limits the Flow verdict checks against.
+  </Card>
+  <Card title="Query your data" icon="magnifying-glass" href="/observability/query">
+    Run TRQL queries against the same telemetry the report reads.
+  </Card>
+</CardGroup>

package/docs/self-hosting/security.mdx

@@ -6,10 +6,27 @@ sidebarTitle: "Security"
 
 We take the security of Trigger.dev seriously, for both Cloud and self-hosted deployments. This page covers how to report a vulnerability, what to expect, and how to stay informed about security releases.
 
+<Note>
+  Unlike Trigger.dev Cloud, the self-hosted setup is optimized for single-tenant use, with code and
+  users you trust. It is not designed to run untrusted code or untrusted payloads.
+</Note>
+
 <Warning>
   Do not report security vulnerabilities through public GitHub issues, pull requests, or Discord. Use one of the private channels below.
 </Warning>
 
+## What is in scope
+
+A self-hosted deployment is a single trust domain: as above, it is built for code and users you trust. Role separation inside an organization is therefore not a security boundary there. Role-based access control comes from a plugin that is not part of the open-source distribution, and without it the permission layer falls back to a permissive ability for session users and personal access tokens. That is deliberate.
+
+**Out of scope for self-hosted:** a member of an organization performing a privileged action inside that same organization, such as renaming or deleting the organization or managing other members. Control who you invite, or use Cloud, if you need that separation.
+
+**In scope from any deployment:** reaching data or actions belonging to an organization the caller is not a member of, or bypassing authentication. Organization is a hard boundary on Trigger.dev Cloud, and Cloud runs this same code, so report these even though your own install is single-tenant.
+
+Tell us which deployment you tested against. The same report can be out of scope for self-hosting and in scope for Cloud.
+
+The [security policy](https://github.com/triggerdotdev/trigger.dev/blob/main/SECURITY.md) is canonical.
+
 ## Reporting a vulnerability
 
 <Steps>

package/docs/tasks/scheduled.mdx

@@ -184,6 +184,30 @@ const createdSchedule = await schedules.create({
   is the assigned time the run will actually start.
 </Note>
 
+### Free-plan minimum window
+
+Schedules created while an organization is on a free plan run no more than once per hour and use a minimum 60-minute window.
+
+- The minimum applies to the **cron cadence**: creating or deploying a schedule whose cron fires more often than once an hour is rejected with an actionable error. Change the cron expression or upgrade before saving.
+- Omitted, zero (`"0m"` / `"0%"`), or smaller windows are treated as the 60-minute minimum. A larger configured window still wins, subject to the usual cap at the next cron occurrence.
+- The policy applies to **all environment types**, including Development.
+- It is captured when the schedule is created. Existing schedules — and schedules created while paid, even after a later downgrade — are **grandfathered** and keep running unchanged.
+- Upgrading does not immediately rewrite existing schedules. A free-created restriction is cleared the next time the schedule is saved (imperative/dashboard) or redeployed (declarative) while the organization is paying.
+- No runs are ever skipped or coalesced: unsupported high-frequency schedules are rejected at create/update time rather than silently thinned out.
+- Self-hosted deployments, and any case where the billing plan can't be determined, are unrestricted.
+
+When a schedule is subject to this policy, the API returns an `appliedSchedulePolicy` object alongside the configured `window`:
+
+```json
+{
+  "window": "0m",
+  "appliedSchedulePolicy": {
+    "minimumWindowSeconds": 3600,
+    "reason": "free_schedule"
+  }
+}
+```
+
 ## Supported cron syntax
 
 ```

package/docs/triggering.mdx

@@ -27,7 +27,7 @@ Trigger tasks **from inside a another task**:
 
 ## Triggering from your backend
 
-When you trigger a task from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable. If you're [using a preview branch](/deployment/preview-branches), you also need to set the `TRIGGER_PREVIEW_BRANCH` environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. [More info on API keys](/apikeys).
+When you trigger a task from your backend code, create a named API key with **Trigger only** access in the environment you want to target and set it as `TRIGGER_SECRET_KEY`. If you're [using a preview branch](/deployment/preview-branches), also set `TRIGGER_PREVIEW_BRANCH`. [More info on API keys](/apikeys).
 
 If a single process needs to trigger across multiple projects, environments, or preview branches, use [`new TriggerClient({...})`](/management/multiple-clients) for each target instead of relying on the global env vars.