@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.16-alpha.1

package/.docs/docs/agents/agent-approval.md

@@ -1,10 +1,10 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Agent approval
+# Human-in-the-loop
 
-Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or running long processes. With agent approval you can suspend a tool call before it executes so a human can approve or decline it, or let tools suspend themselves to request additional context from the user.
+Agents sometimes require the same [human-in-the-loop (HITL)](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or running long processes. With human-in-the-loop you can suspend a tool call before it executes so a human can approve or decline it, or let tools suspend themselves to request additional context from the user.
 
-## When to use agent approval
+## When to use human-in-the-loop
 
 - **Destructive or irreversible actions** such as deleting records or sending emails, or alternatively processing payments.
 - **Cost-heavy operations** like calling expensive third-party APIs where you want to verify arguments first.
@@ -12,7 +12,7 @@ Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/wor
 
 ## Quickstart
 
-Mark a tool with `requireApproval: true`, then check for the `tool-call-approval` chunk in the stream to approve or decline:
+Mark a tool with `requireApproval: true`, then check for the `tool-call-approval` chunk in the stream to approve or decline the action:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -48,7 +48,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
+> **Note:** Human-in-the-loop uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
 >
 > Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.
 
@@ -90,6 +90,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Explaining a decline
+
+`declineToolCall()`, `declineToolCallGenerate()`, and `declineNetworkToolCall()` accept an optional `reason`. The reason is returned to the model in place of the tool result, so the model can adjust instead of retrying blindly. It's also stored on the tool call's `approval` metadata, so it's still there when the conversation is recalled.
+
+```typescript
+const declined = await agent.declineToolCall({
+  runId: stream.runId,
+  toolCallId,
+  reason: 'Reading other users PII is not allowed, ask the user for their own email instead',
+})
+```
+
+Without a `reason`, the model receives the default message `Tool call was not approved by the user`.
+
 #### Conditional approval with a function
 
 Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:

package/.docs/docs/agents/code-mode.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.38.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response.
 
@@ -134,7 +134,7 @@ The generated code for `sales_code` can't call an inventory tool, and the revers
 
 ## Remote sandboxes
 
-By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/reference/workspace/e2b-sandbox)), where the host paths don't exist.
+By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/integrations/sandboxes/e2b)), where the host paths don't exist.
 
 Remote sandboxes need a transport that writes the program into the sandbox filesystem. For E2B, pass the included `E2BCodeModeTransport` as the second argument to `createCodeMode`:
 
@@ -164,9 +164,24 @@ const { tool, instructions } = createCodeMode(
 
 `isolated-vm` is a native addon, and on Node.js 20 and later the host process must be started with the `--no-node-snapshot` flag. See the [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport) for setup details.
 
+When the host can't install native addons or set Node.js flags, which is common on serverless platforms, use [`QuickJsCodeModeTransport`](https://mastra.ai/reference/tools/quickjs-transport) from `@mastra/quickjs` instead. It gives the same in-process boundary using a QuickJS runtime compiled to WebAssembly, at the cost of slower execution:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { QuickJsCodeModeTransport } from '@mastra/quickjs'
+
+const { tool, instructions } = createCodeMode(
+  { tools }, // no sandbox needed
+  new QuickJsCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport) for a side-by-side comparison.
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
+- [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/networks.md

@@ -4,7 +4,7 @@
 
 > **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
-> See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> See the [migration guide](https://mastra.ai/reference/migrations/network-to-supervisor) to upgrade.
 
 A **routing agent** uses an LLM to interpret a request and decide which primitives (subagents, workflows, or tools) to call, in what order, and with what data.
 
@@ -181,4 +181,4 @@ Requirements for automatic resumption:
 ## Related
 
 - [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
-- [Migration: `.network()` to supervisor agents](https://mastra.ai/guides/migrations/network-to-supervisor)
+- [Migration: `.network()` to supervisor agents](https://mastra.ai/reference/migrations/network-to-supervisor)

package/.docs/docs/agents/overview.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Agents overview
+# Agents
 
 Agents use LLMs and tools to solve open-ended tasks. They reason about goals and decide which tools to use. They retain conversation memory and continue iterating until the model emits a final answer or an optional stop condition is met.
 
@@ -163,7 +163,7 @@ Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more i
 
 ## Use your agent
 
-After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/using-tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. Visit the [guides section](https://mastra.ai/guides) to learn how to use agents in your framework of choice.
+After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/using-tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. See [Integrations](https://mastra.ai/integrations) to use agents in your application framework.
 
 When referencing an agent from your Mastra instance, use `mastra.getAgentById()` to ensure it has access to shared services such as instance-level storage, logging, and agent registry. A directly imported agent can still work with its own local configuration, but it won't have access to those shared services.
 
@@ -203,18 +203,18 @@ Once your agent is running, use this table to find the right page for what you w
 | Give your agent tools to call external APIs or services        | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
 | Keep context and preferences across conversations              | [Memory](https://mastra.ai/docs/memory/overview)                       |
 | Get typed objects back instead of plain text                   | [Structured output](https://mastra.ai/docs/agents/structured-output)   |
-| Human-in-the-loop: Pause execution and wait for human approval | [Approval](https://mastra.ai/docs/agents/agent-approval)               |
+| Human-in-the-loop: Pause execution and wait for human approval | [Human-in-the-loop](https://mastra.ai/docs/agents/agent-approval)      |
 | Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)     |
 | Register subagents                                             | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
 | Intercept or transform messages before and after generation    | [Processors](https://mastra.ai/docs/agents/processors)                 |
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
 | Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/capabilities/subagents)         |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
-| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/guides/voice/overview)                       |
-| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels/overview)      |
+| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/reference/voice/overview)                    |
+| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels)               |
 
 ## Multi-agent systems
 
 A multi-agent system uses multiple agents to solve a task that's too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
 
-Read the [conceptual overview of multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems) to learn how you can apply different patterns with Mastra.
+Read the [conceptual overview of multi-agent systems](https://mastra.ai/docs/guides/multi-agent-systems) to learn how you can apply different patterns with Mastra.

package/.docs/docs/agents/processors.md

@@ -432,7 +432,7 @@ See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processo
 
 ## Response caching
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
@@ -544,7 +544,7 @@ This means the cache key is derived from the resolved `LanguageModelV2Prompt` Ma
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
-Multimodal prompts are included too. Image and file parts reach the key by value: a URL contributes its full href, and inline binary data (`Uint8Array`, `ArrayBuffer`) contributes a digest of its bytes. Two requests that differ only in which image they reference therefore get different cache entries.
+Multimodal prompts are included too. Image and file parts reach the key by value: the key includes a URL's full href, and a digest of the bytes for inline binary data (`Uint8Array`, `ArrayBuffer`). Requests that differ only in which image they reference therefore get different cache entries.
 
 #### Customize the cache key
 
@@ -664,7 +664,7 @@ export class SteeringReminderProcessor implements Processor {
 }
 ```
 
-A transient signal still appears in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and it never appears in stored thread history. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
+A transient signal is still in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and stored thread history never includes it. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
 
 ### Emit custom stream events
 

package/.docs/docs/agents/using-tools.md

@@ -353,7 +353,7 @@ Agent-level and per-execution hooks merge per key: passing only `beforeToolCall`
 
 Tools support lifecycle hooks that allow you to monitor different stages of tool execution during streaming. These hooks are particularly useful for logging or analytics.
 
-For generic `writer` API usage, see [Streaming](https://mastra.ai/guides/concepts/streaming).
+For generic `writer` API usage, see [Streaming](https://mastra.ai/docs/guides/streaming).
 
 ### Available Hooks
 

package/.docs/docs/browser/overview.md

@@ -1,15 +1,15 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Browser overview
+# Browser
 
 Browser support enables agents to move through websites, interact with page elements, fill forms, and extract data. Mastra provides browser capabilities through SDK providers that wrap browser automation libraries and a CLI provider for agents that drive browsers through command-line tools.
 
 Mastra supports three SDK providers and one CLI provider:
 
-- [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
-- [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
-- [**FirecrawlBrowser**](https://mastra.ai/docs/browser/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
-- [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
+- [**AgentBrowser**](https://mastra.ai/integrations/browsers/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
+- [**Stagehand**](https://mastra.ai/integrations/browsers/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
+- [**FirecrawlBrowser**](https://mastra.ai/integrations/browsers/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
+- [**BrowserViewer**](https://mastra.ai/integrations/browsers/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
 - [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
 ## When to use browser
@@ -178,10 +178,10 @@ const browser = new AgentBrowser({
 
 ## Next steps
 
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
-- [Stagehand](https://mastra.ai/docs/browser/stagehand)
-- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
+- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
+- [Firecrawl](https://mastra.ai/integrations/browsers/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
-- [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
+- [BrowserViewer](https://mastra.ai/integrations/browsers/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)
 - 📹 [Mastra browser capabilities workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)

package/.docs/docs/browser/recording.md

@@ -1,12 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Browser recording (beta)
+# Browser recording
 
 **Added in:** `@mastra/core@1.43.0`
 
 Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 ## When to use browser recording
 
@@ -115,6 +115,6 @@ Use shorter recordings when possible. Long browser sessions produce larger files
 
 ## Next steps
 
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
-- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
+- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
 - [Browser overview](https://mastra.ai/docs/browser/overview)

package/.docs/docs/capabilities/{channels/overview.md → channels.md}

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Channels overview
+# Channels
 
 **Added in:** `@mastra/core@1.22.0`
 
@@ -8,14 +8,15 @@ Channels connect agents to messaging and collaboration platforms like Slack, Mic
 
 Start with the page for your platform:
 
-- [Slack](https://mastra.ai/docs/capabilities/channels/slack)
-- [Microsoft Teams](https://mastra.ai/docs/capabilities/channels/teams)
-- [Discord](https://mastra.ai/docs/capabilities/channels/discord)
-- [Telegram](https://mastra.ai/docs/capabilities/channels/telegram)
-- [WhatsApp](https://mastra.ai/docs/capabilities/channels/whatsapp)
-- [iMessage](https://mastra.ai/docs/capabilities/channels/imessage)
+- [Discord](https://mastra.ai/integrations/channels/discord)
+- [GitHub](https://mastra.ai/integrations/channels/github)
+- [iMessage](https://mastra.ai/integrations/channels/imessage)
+- [Microsoft Teams](https://mastra.ai/integrations/channels/teams)
+- [Slack](https://mastra.ai/integrations/channels/slack)
+- [Telegram](https://mastra.ai/integrations/channels/telegram)
+- [WhatsApp](https://mastra.ai/integrations/channels/whatsapp)
 
-[More](https://mastra.ai/docs/capabilities/channels/other-adapters) lists additional platforms. Mastra channels work with compatible [Chat SDK adapters](https://chat-sdk.dev/adapters) beyond the platforms listed here, and the same Mastra configuration pattern applies across adapters.
+[Other adapters](#other-adapters) lists additional platforms. Mastra channels work with compatible [Chat SDK adapters](https://chat-sdk.dev/adapters) beyond the platforms listed here, and the same Mastra configuration pattern applies across adapters.
 
 ## When to use channels
 
@@ -274,6 +275,68 @@ export const mastra = new Mastra({
 
 Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
 
+## Other adapters
+
+Mastra channels use Chat SDK adapters, so the platform guides aren't the full list of supported platforms. Use any Chat SDK platform adapter that exports an adapter factory compatible with `channels.adapters`.
+
+### Adapter catalog
+
+The [Chat SDK adapter catalog](https://chat-sdk.dev/adapters) is the canonical source for available adapters. The list below is a snapshot and may not always be up to date.
+
+At the time of writing, Chat SDK lists adapters for:
+
+- AgentPhone
+- Baileys WhatsApp
+- Discord
+- GitHub
+- Google Chat
+- iMessage
+- Kapso
+- Lark / Feishu
+- Linear
+- Liveblocks
+- Matrix
+- Mattermost
+- Messenger
+- Novu
+- Resend
+- Sendblue
+- Telegram
+- Twilio
+- Velt
+- Web
+- Webex
+- WeChat
+- WhatsApp Business Cloud
+- X
+- Zalo
+- Zernio
+
+Check the adapter's docs for its package name, credential variables, webhook requirements, and platform-specific behavior.
+
+### Use the same Mastra wiring
+
+The Mastra side of each Chat SDK adapter follows the same setup. Install the adapter package and add its factory to `channels.adapters`. Then configure the platform credentials and point its webhook to the generated Mastra route.
+
+Use one of the platform guides as a reference for the Mastra wiring:
+
+- [Discord](https://mastra.ai/integrations/channels/discord)
+- [Microsoft Teams](https://mastra.ai/integrations/channels/teams)
+- [Slack](https://mastra.ai/integrations/channels/slack)
+- [Telegram](https://mastra.ai/integrations/channels/telegram)
+- [WhatsApp](https://mastra.ai/integrations/channels/whatsapp)
+
+### Check the adapter docs
+
+Before wiring a new adapter into Mastra, check the adapter docs for:
+
+- Attachment, card, and rich message support.
+- Credential environment variables.
+- Required platform permissions or scopes.
+- Whether regular messages require long-running listeners or polling.
+- Whether the platform needs separate routes for setup, events, or interactions.
+- Webhook verification behavior.
+
 ## Related
 
 - [Channels reference](https://mastra.ai/reference/agents/channels)

package/.docs/docs/capabilities/subagents.md

@@ -16,7 +16,7 @@ Common use cases:
 - Multi-step tasks that need different expertise at each stage
 - Tasks where you need fine-grained control over delegation behavior
 
-> **Note:** A parent agent that coordinates subagents is often called a supervisor. The supervisor pattern is one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/guides/concepts/multi-agent-systems).
+> **Note:** A parent agent that coordinates subagents is often called a supervisor. The supervisor pattern is one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/docs/guides/multi-agent-systems).
 
 ## Quickstart
 
@@ -113,7 +113,7 @@ The `context` object includes:
 
 ### Request context at the delegation boundary
 
-Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run doesn't affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -134,6 +134,9 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 
 - `context.bail()`: Stop the parent agent's loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
+
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -444,11 +447,11 @@ Version overrides propagate automatically through delegation. See [Subagent vers
 
 - [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Subagent versioning](https://mastra.ai/reference/editor/versioning)
-- [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
+- [Guide: Research coordinator](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.streamUntilIdle() reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
 - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
 - [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)
-- [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)
+- [Concept: Multi-agent systems](https://mastra.ai/docs/guides/multi-agent-systems)
 - 📹 [Mastra supervisor agents workshop](https://www.youtube.com/watch?v=FNb2fL9WhQg\&t=1872s)

package/.docs/docs/connections/overview.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Connections overview
+# Connections
 
 Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
 

package/.docs/docs/datasets/overview.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Datasets overview
+# Datasets
 
 **Added in:** `@mastra/core@1.4.0`
 

package/.docs/docs/datasets/running-experiments.md

@@ -206,6 +206,55 @@ The `experiment.run.finished` event is awaited before Mastra persists the final
 
 The exported event types are `ExperimentEvent`, `ExperimentRunStartedEvent`, `ExperimentItemCompletedEvent`, and `ExperimentRunFinishedEvent`. Use the discriminated `type` field to narrow an event before reading event-specific properties.
 
+## Lifecycle hooks
+
+Use lifecycle hooks to prepare state before a target runs and clean it up afterwards. This is useful when an item can't be evaluated against an empty environment. A run might need a fixture file copied into the agent's workspace, or a sandbox provisioned before the agent can touch it.
+
+Hooks run at two levels. `beforeAll` and `afterAll` run once per experiment, and `beforeEach` and `afterEach` run once per item:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'document-agent',
+  scorers: ['accuracy'],
+  beforeAll: async ({ experimentId }) => {
+    await createWorkspace(experimentId)
+  },
+  beforeEach: async ({ item }) => {
+    await copyFixture(item.metadata?.fixture)
+  },
+  afterEach: async ({ item, result }) => {
+    await clearWorkspaceFiles(item.id)
+  },
+  afterAll: async ({ summary }) => {
+    await deleteWorkspace(summary.experimentId)
+  },
+})
+```
+
+Every hook can be async. Each one receives the `experimentId`, the `mastra` instance, and the run-level `signal`, so long-running setup can be cancelled along with the experiment. The per-item hooks also receive `item`. The teardown hooks receive the result they follow: `afterEach` receives the item's `result` including scores, and `afterAll` receives the `summary` that's about to be returned.
+
+The item passed to hooks exposes `id`, `input`, `groundTruth`, and `metadata`. Fields that control execution, such as tool mocks and scorer selection, aren't exposed, so a hook can't change how the item runs.
+
+### Hook failures
+
+Each hook has a different consequence when it throws, based on how much of the run depends on it:
+
+| Hook         | On failure                                                                       |
+| ------------ | -------------------------------------------------------------------------------- |
+| `beforeAll`  | Fails the experiment. No items run.                                              |
+| `beforeEach` | Fails that item with `EXPERIMENT_ITEM_BEFORE_EACH_FAILED`. Other items continue. |
+| `afterEach`  | Logged. The item's recorded outcome doesn't change.                              |
+| `afterAll`   | Logged. The returned summary doesn't change.                                     |
+
+When `beforeAll` fails, the experiment is marked failed and the `experiment.run.finished` event is still emitted before the error propagates.
+
+When `beforeEach` fails, the target and its scorers are skipped for that item, since the item's preconditions were never met. `afterEach` is also skipped for that item, on the basis that setup which didn't finish owns its own cleanup.
+
+Teardown failures are logged rather than propagated. By the time `afterEach` runs, the target has already produced a real result, and discarding it because cleanup was untidy would lose the data the experiment was run to collect.
+
+`afterAll` runs on every exit path, including when the experiment fails, when `beforeAll` fails, and when an [event observer](#observe-experiment-events) fails, so teardown isn't skipped when something goes wrong. It runs at most once per experiment.
+
 ## Tool mocks
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.

package/.docs/docs/deployment/cloud-providers.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Deploy to cloud providers
+# Cloud providers
 
 Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the deployment process.
 
@@ -10,14 +10,16 @@ Mastra provides a platform to deploy your server to the cloud. Read the [Mastra
 
 ## Cloud providers
 
-The following guides show how to deploy Mastra to specific cloud providers:
+The following pages show you how to deploy Mastra to specific cloud providers.
 
-- [Amazon Bedrock AgentCore](https://mastra.ai/guides/deployment/aws-bedrock-agentcore)
-- [Amazon EC2](https://mastra.ai/guides/deployment/amazon-ec2)
-- [AWS Lambda](https://mastra.ai/guides/deployment/aws-lambda)
-- [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
-- [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
-- [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
-- [Kubernetes](https://mastra.ai/guides/deployment/kubernetes)
-- [Netlify](https://mastra.ai/guides/deployment/netlify)
-- [Vercel](https://mastra.ai/guides/deployment/vercel)
+- [Amazon Bedrock AgentCore](https://mastra.ai/integrations/deploy/aws-bedrock-agentcore)
+- [Amazon EC2](https://mastra.ai/integrations/deploy/amazon-ec2)
+- [AWS Lambda](https://mastra.ai/integrations/deploy/aws-lambda)
+- [Azure App Services](https://mastra.ai/integrations/deploy/azure-app-services)
+- [Cloudflare](https://mastra.ai/integrations/deploy/cloudflare)
+- [Digital Ocean](https://mastra.ai/integrations/deploy/digital-ocean)
+- [Inngest](https://mastra.ai/integrations/deploy/inngest)
+- [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
+- [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Temporal](https://mastra.ai/integrations/deploy/temporal)
+- [Vercel](https://mastra.ai/integrations/deploy/vercel)

package/.docs/docs/deployment/mastra-server.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Deploy a Mastra server
+# Mastra server
 
 Mastra compiles your application into a standalone Node.js server that can run on any platform supporting Node.js, Bun, or Deno.
 

package/.docs/docs/deployment/monorepo.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Deploy in a monorepo
+# Monorepo
 
 Deploying Mastra in a monorepo follows the same process as a standalone application. This guide covers monorepo-specific considerations. For the core build and deployment steps, see [Deploy a Mastra Server](https://mastra.ai/docs/deployment/mastra-server).
 

package/.docs/docs/deployment/overview.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Deployment overview
+# Deploy
 
 Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server, integrate with an existing web framework, deploy to cloud providers, or use [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) for observability, Studio, and server deployment.
 
@@ -43,14 +43,17 @@ Mastra applications can be deployed to cloud providers and serverless platforms.
 
 Use this option for auto-scaling, minimal infrastructure management, or when you're already using one of these platforms.
 
-- [Amazon EC2](https://mastra.ai/guides/deployment/amazon-ec2)
-- [AWS Lambda](https://mastra.ai/guides/deployment/aws-lambda)
-- [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
-- [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
-- [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
-- [Kubernetes](https://mastra.ai/guides/deployment/kubernetes)
-- [Netlify](https://mastra.ai/guides/deployment/netlify)
-- [Vercel](https://mastra.ai/guides/deployment/vercel)
+- [Amazon Bedrock AgentCore](https://mastra.ai/integrations/deploy/aws-bedrock-agentcore)
+- [Amazon EC2](https://mastra.ai/integrations/deploy/amazon-ec2)
+- [AWS Lambda](https://mastra.ai/integrations/deploy/aws-lambda)
+- [Azure App Services](https://mastra.ai/integrations/deploy/azure-app-services)
+- [Cloudflare](https://mastra.ai/integrations/deploy/cloudflare)
+- [Digital Ocean](https://mastra.ai/integrations/deploy/digital-ocean)
+- [Inngest](https://mastra.ai/integrations/deploy/inngest)
+- [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
+- [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Temporal](https://mastra.ai/integrations/deploy/temporal)
+- [Vercel](https://mastra.ai/integrations/deploy/vercel)
 
 ### Sandbox
 
@@ -72,7 +75,7 @@ Use these guides when adding Mastra to an existing Next.js or Astro application.
 
 Mastra workflows run using the built-in execution engine by default. For production workloads requiring managed infrastructure, workflows can also be deployed to specialized platforms like [Inngest](https://www.inngest.com) that provide step memoization, automatic retries, and real-time monitoring.
 
-Visit the [Workflow Runners guide](https://mastra.ai/docs/deployment/workflow-runners) for execution options and the [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest) for setup instructions.
+Visit the [Workflow Runners guide](https://mastra.ai/docs/deployment/workflow-runners) for execution options and the [Inngest deployment guide](https://mastra.ai/integrations/deploy/inngest) for setup instructions.
 
 ## Workers
 

package/.docs/docs/deployment/sandbox.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Deploy to a sandbox
+# Sandbox
 
 `@mastra/deployer-sandbox` deploys a full Mastra server, including Studio, into an ephemeral workspace sandbox and returns a live public URL. Repeat deployments can finish faster because the deployer skips dependency installation.
 
@@ -17,9 +17,9 @@ Sandboxes have provider-enforced runtime caps and expire. For production hosting
 
 The deployer works with any workspace sandbox that supports networking (public port URLs):
 
-- [Vercel Sandbox](https://mastra.ai/reference/workspace/vercel-sandbox) (`@mastra/vercel`)
-- [E2B](https://mastra.ai/reference/workspace/e2b-sandbox) (`@mastra/e2b`)
-- [Daytona](https://mastra.ai/reference/workspace/daytona-sandbox) (`@mastra/daytona`)
+- [Vercel Sandbox](https://mastra.ai/integrations/sandboxes/vercel) (`@mastra/vercel`)
+- [E2B](https://mastra.ai/integrations/sandboxes/e2b) (`@mastra/e2b`)
+- [Daytona](https://mastra.ai/integrations/sandboxes/daytona) (`@mastra/daytona`)
 
 Provider authors can add support by implementing the optional `networking` capability on [`WorkspaceSandbox`](https://mastra.ai/reference/workspace/sandbox).