@mastra/mcp-docs-server 1.2.4 → 1.2.5-alpha.3

package/.docs/docs/agent-builder/deploying.md

@@ -103,7 +103,7 @@ new Mastra({
 
 `S3Filesystem` uses the default AWS credential chain (environment variables, `~/.aws` config, IAM roles, EC2 instance profile). For long-running deployments, use a credential provider function so credentials refresh automatically.
 
-`DockerSandbox` and `VercelSandbox` are alternative cloud sandbox providers, pick whichever matches your runtime.
+`DockerSandbox`, `VercelSandbox`, and `VercelServerlessSandbox` are alternative cloud sandbox providers. Pick whichever matches your runtime.
 
 > **Warning:** A local sandbox can't run commands safely in a shared environment. Always register a cloud sandbox provider and reference it in the workspace config before deploying.
 

package/.docs/docs/agent-controller/overview.md

@@ -42,7 +42,7 @@ You could assemble all of this yourself on top of the [Agent class](https://mast
 - **Subagents**: Spawn focused child agents with constrained tools for subtasks, optionally forking the parent conversation. See [Subagents](https://mastra.ai/docs/agent-controller/subagents).
 - **Tool approvals and permissions**: Configure which tools require user confirmation, grant session-wide exceptions, and handle interactive tool suspension. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals).
 - **Model management**: Switch models per-mode at runtime, track usage, and resolve gateway-backed models through Mastra's [model router](https://mastra.ai/models).
-- **Follow-ups and steering**: Queue messages while the agent is running, or inject mid-stream instructions to redirect the agent. Built on [signals](https://mastra.ai/docs/agents/signals).
+- **Follow-ups and steering**: Queue messages while the agent is running, or inject mid-stream instructions to redirect the agent. Built on [signals](https://mastra.ai/docs/long-running-agents/signals).
 - **Event system**: Subscribe to typed events (message updates, mode changes, tool approvals) or coalesced `AgentControllerDisplayState` snapshots to drive your UI. See [Events](https://mastra.ai/reference/agent-controller/agent-controller-class).
 - **Observational memory**: Automatic summarization and reflection across threads for long-running agent sessions. See [Observational memory](https://mastra.ai/docs/memory/observational-memory).
 

package/.docs/docs/agent-controller/session.md

@@ -101,7 +101,7 @@ A user may want to add to the conversation while the agent is still working. Ins
 const queued = agentController.session.followUps.count()
 ```
 
-Queue a follow-up with `agentController.followUp({ content })`. To redirect the agent mid-run instead of waiting, use `agentController.steer({ content })`. Both build on [signals](https://mastra.ai/docs/agents/signals).
+Queue a follow-up with `agentController.followUp({ content })`. To redirect the agent mid-run instead of waiting, use `agentController.steer({ content })`. Both build on [signals](https://mastra.ai/docs/long-running-agents/signals).
 
 ## State
 

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

@@ -203,7 +203,7 @@ Once your agent is running, use this table to find the right page for what you w
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
 | Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/agents/supervisor-agents)       |
 | 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/docs/agents/adding-voice)                    |
+| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/docs/voice/overview)                         |
 | Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/agents/channels)                     |
 
 ## Multi-agent systems

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

@@ -638,7 +638,7 @@ Do not mention the reminder to the user or quote the tags back to them.`,
 await agent.generate('Your prompt', { maxSteps: MAX_STEPS })
 ```
 
-> **Note:** Reactive signals default to `tagName: 'system-reminder'`. Visit [Signals](https://mastra.ai/docs/agents/signals) for more on processor-emitted signals.
+> **Note:** Reactive signals default to `tagName: 'system-reminder'`. Visit [Signals](https://mastra.ai/docs/long-running-agents/signals) for more on processor-emitted signals.
 
 ### Emit custom stream events
 

package/.docs/docs/agents/supervisor-agents.md

@@ -374,7 +374,7 @@ Success criteria:
 
 ## Running subagents in the background
 
-Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
+Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
 
 Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration) on the Mastra instance, then opt subagents in on the supervisor:
 
@@ -399,7 +399,7 @@ const stream = await supervisor.streamUntilIdle('Research AI in education and wr
 
 Use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) instead of `stream()` so the stream stays open until the subagents complete and the supervisor has had a chance to respond to their results.
 
-If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/agents/background-tasks) for details.
+If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/long-running-agents/background-tasks) for details.
 
 ## Subagent versioning
 
@@ -420,7 +420,7 @@ Version overrides propagate automatically through delegation. See [Subagent vers
 
 ## Related
 
-- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Subagent versioning](https://mastra.ai/docs/editor/overview)
 - [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)

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

@@ -415,7 +415,7 @@ Note that for subagents, you'll see two different identifiers in stream response
 
 - [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
 - [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
-- [Background tasks](https://mastra.ai/docs/agents/background-tasks): Run long-running tools without blocking the agent loop
+- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks): Run long-running tools without blocking the agent loop
 - [MCP overview](https://mastra.ai/docs/mcp/overview)
 - [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
 - [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output

package/.docs/docs/{agents → long-running-agents}/background-tasks.md

@@ -121,7 +121,7 @@ If the agent has `backgroundTasks.disabled: true`, every tool call runs synchron
 
 ## Background tasks related stream chunks
 
-When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
+When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/long-running-agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
 
 | Chunk type                  | When it fires                                                                          | Emitted by     |
 | --------------------------- | -------------------------------------------------------------------------------------- | -------------- |
@@ -376,7 +376,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
-- [Durable agents](https://mastra.ai/docs/agents/durable-agents)
+- [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
 - [Storage](https://mastra.ai/docs/memory/storage)

package/.docs/docs/{agents → long-running-agents}/durable-agents.md

@@ -199,7 +199,7 @@ await durableAgent.stream('Research topic', {
 })
 ```
 
-> **Note:** Visit [Background tasks](https://mastra.ai/docs/agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
+> **Note:** Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
 
 ## Cleanup
 
@@ -228,6 +228,6 @@ await durableAgent.resume(runId, { approved: true })
 
 - [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent)
 - [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent)
-- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest)
 - [Agent overview](https://mastra.ai/docs/agents/overview)

package/.docs/docs/{agents → long-running-agents}/goals.md

@@ -110,5 +110,5 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 ## Related
 
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
-- [Signal providers](https://mastra.ai/docs/agents/signal-providers) — how the objective is projected into context
+- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers) — how the objective is projected into context
 - [Memory storage](https://mastra.ai/docs/memory/storage) — the storage backend goals require

package/.docs/docs/{agents → long-running-agents}/heartbeats.md

@@ -6,7 +6,7 @@
 
 > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-A heartbeat runs an agent on a cron schedule. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/agents/signals) into a thread or as a threadless `agent.generate()` run. Use heartbeats for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+A heartbeat runs an agent on a cron schedule. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless `agent.generate()` run. Use heartbeats for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 
 Heartbeats are persisted, so they survive restarts and redeploys. Manage them at runtime through `mastra.heartbeats`, the canonical create, read, update, and delete (CRUD) surface.
 
@@ -73,7 +73,7 @@ Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing i
 
 ### Threaded
 
-With a `threadId`, the heartbeat sends a [signal](https://mastra.ai/docs/agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded heartbeats require a `resourceId` alongside the `threadId`.
+With a `threadId`, the heartbeat sends a [signal](https://mastra.ai/docs/long-running-agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded heartbeats require a `resourceId` alongside the `threadId`.
 
 ```typescript
 await mastra.heartbeats.create({
@@ -85,9 +85,9 @@ await mastra.heartbeats.create({
 })
 ```
 
-Threaded heartbeats accept extra fields that control how the signal behaves. They mirror the options [`agent.sendSignal`](https://mastra.ai/docs/agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
+Threaded heartbeats accept extra fields that control how the signal behaves. They mirror the options [`agent.sendSignal`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
 
-- `signalType`: the [signal type](https://mastra.ai/docs/agents/signals) to send, for example `notification` or `system-reminder`. Defaults to `notification`.
+- `signalType`: the [signal type](https://mastra.ai/docs/long-running-agents/signals) to send, for example `notification` or `system-reminder`. Defaults to `notification`.
 - `tagName`: the XML tag the signal renders as. Defaults to `heartbeat`, so a fire surfaces to the agent as `<heartbeat>…</heartbeat>`.
 - `attributes`: values rendered onto the signal's XML tag.
 - `ifActive`: behavior when the thread is already streaming, as `{ behavior, attributes }`. `behavior` is one of `deliver`, `persist`, or `discard`.
@@ -209,5 +209,5 @@ Hook exceptions are caught and logged. They never re-route the worker or trigger
 
 ## Related
 
-- [Signals](https://mastra.ai/docs/agents/signals): the delivery mechanism behind threaded heartbeats.
+- [Signals](https://mastra.ai/docs/long-running-agents/signals): the delivery mechanism behind threaded heartbeats.
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): run a workflow, rather than an agent, on a cron schedule.

package/.docs/docs/{agents → long-running-agents}/signal-providers.md

@@ -6,7 +6,7 @@
 
 > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/agents/signals) into subscribed agent threads.
+A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/long-running-agents/signals) into subscribed agent threads.
 
 ## When to use a signal provider
 
@@ -20,7 +20,7 @@ If you only need to push a one-off event into a thread, call [`agent.sendNotific
 
 ## How signal providers work
 
-A signal provider is the producing side of the [signals](https://mastra.ai/docs/agents/signals) system. It brings external events into a thread, while the signal APIs control how the thread consumes them.
+A signal provider is the producing side of the [signals](https://mastra.ai/docs/long-running-agents/signals) system. It brings external events into a thread, while the signal APIs control how the thread consumes them.
 
 A signal provider combines three capabilities:
 
@@ -218,7 +218,7 @@ export const devAgent = new Agent({
 ## Related
 
 - [Guide: Building a signal provider](https://mastra.ai/guides/guide/signal-provider)
-- [Signals](https://mastra.ai/docs/agents/signals)
-- [Notification signals](https://mastra.ai/docs/agents/signals)
+- [Signals](https://mastra.ai/docs/long-running-agents/signals)
+- [Notification signals](https://mastra.ai/docs/long-running-agents/signals)
 - [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider)
 - [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)

package/.docs/docs/memory/working-memory.md

@@ -399,7 +399,7 @@ const response = await agent.generate('What do you know about me?', {
 
 ## Opt in to state signals (experimental)
 
-By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/agents/signals) instead by setting `useStateSignals: true`:
+By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/long-running-agents/signals) instead by setting `useStateSignals: true`:
 
 ```typescript
 const memory = new Memory({

package/.docs/docs/observability/config.md

@@ -96,8 +96,7 @@ export const observability = new Observability({
 In serverless environments, flush observability exporters before the runtime pauses or exits:
 
 ```ts
-const observability = mastra.getObservability()
-await observability.flush()
+await mastra.observability.flush()
 ```
 
 Use external storage in serverless environments instead of local file storage. For storage selection and routing, see [Storage](https://mastra.ai/docs/observability/storage).

package/.docs/docs/server/pubsub.md

@@ -12,7 +12,7 @@ Several built-in systems publish and subscribe to events through the same pub/su
 
 - **Workflow execution**: The scheduler publishes a `workflow.start` event, and a long-lived worker consumes it to run the workflow. Step and lifecycle events flow over pub/sub during execution.
 - **Scheduled workflows**: The scheduler dispatches due runs by publishing to the workflow topic. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
-- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/agents/background-tasks).
+- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/long-running-agents/background-tasks).
 - **Agent signals**: Sending a signal to an active agent run publishes an event on a thread topic, so a run executing in another process receives the signal.
 - **Resumable streams**: Stream chunks are published per run, so a client that reconnects can replay what it missed.
 
@@ -122,5 +122,5 @@ export const mastra = new Mastra({
 
 - [PubSub reference](https://mastra.ai/reference/pubsub/base)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
-- [Background task streaming](https://mastra.ai/docs/agents/background-tasks)
+- [Background task streaming](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)

package/.docs/docs/voice/overview.md

@@ -4,9 +4,9 @@
 
 Mastra's Voice system provides a unified interface for voice interactions, enabling text-to-speech (TTS), speech-to-text (STT), and real-time speech-to-speech (STS) capabilities in your applications.
 
-## Adding voice to agents
+## Add voice to agents
 
-To learn how to integrate voice capabilities into your agents, check out the [Adding Voice to Agents](https://mastra.ai/docs/agents/adding-voice) documentation. This section covers how to use both single and multiple voice providers, as well as real-time interactions.
+Pass a voice provider to an agent with the `voice` property. The same property supports text-to-speech (TTS), speech-to-text (STT), and real-time speech-to-speech (STS), depending on the provider you configure.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -1139,7 +1139,7 @@ const voiceAgent = new Agent({
 })
 ```
 
-### Using Multiple Voice Providers
+### Using multiple voice providers
 
 This example demonstrates how to create and use two different voice providers in Mastra: OpenAI for speech-to-text (STT) and PlayAI for text-to-speech (TTS).
 

package/.docs/docs/voice/speech-to-speech.md

@@ -54,7 +54,87 @@ const micStream = getMicrophoneStream()
 await agent.voice.send(micStream)
 ```
 
-For integrating Speech-to-Speech capabilities with agents, refer to the [Adding Voice to Agents](https://mastra.ai/docs/agents/adding-voice) documentation.
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).
+
+## Use tools in realtime sessions
+
+Realtime voice providers can use tools configured on the agent. Add the tools to the `Agent` definition, then connect and send audio through the voice provider:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import { calculate, search } from '../tools'
+
+export const agent = new Agent({
+  id: 'speech-to-speech-agent',
+  name: 'Speech-to-Speech Agent',
+  instructions: 'You are a helpful assistant with speech-to-speech capabilities.',
+  model: 'openai/gpt-5.5',
+  tools: {
+    search,
+    calculate,
+  },
+  voice: new OpenAIRealtimeVoice(),
+})
+```
+
+## Listen for realtime events
+
+Realtime voice providers emit events you can use to update your UI, play assistant audio, log transcriptions, and handle errors:
+
+```typescript
+agent.voice.on('speaking', ({ audio }) => {
+  playAudio(audio)
+})
+
+agent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`)
+})
+
+agent.voice.on('error', error => {
+  console.error('Voice error:', error)
+})
+```
+
+Event names and payloads vary by provider. Check the provider section below or the provider reference for the full event list.
+
+## Per-session voice instances
+
+A static `voice` instance is shared across every request. This works for one-shot text-to-speech, but real-time and speech-to-speech providers store session state such as the WebSocket connection, tools, instructions, and request context. If one agent handles several live sessions at once, a shared instance can let one session overwrite another session's state.
+
+Provide `voice` as a resolver when each live session needs its own voice instance. Mastra runs the resolver on each `getVoice()` call and returns a fresh instance for that request context:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { RequestContext } from '@mastra/core/request-context'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+
+export const agent = new Agent({
+  id: 'support-line',
+  name: 'Support Line',
+  instructions: ({ requestContext }) => `Help user ${requestContext.get('user')}.`,
+  model: 'openai/gpt-5.5',
+  voice: ({ requestContext }) =>
+    new OpenAIRealtimeVoice({
+      apiKey: requestContext.get('apiKey'),
+    }),
+})
+
+const requestContext = new RequestContext()
+requestContext.set('user', 'user-123')
+requestContext.set('apiKey', process.env.OPENAI_API_KEY)
+
+const voice = await agent.getVoice({ requestContext })
+await voice.connect()
+```
+
+When you use a resolver:
+
+- Each call to `getVoice()` returns a new instance, so concurrent sessions don't share state.
+- Mastra doesn't add tools or instructions to a resolver instance. Configure them inside the resolver or on the provider.
+- You own the returned instance lifecycle, so call `disconnect()` or `close()` when the session ends.
+
+The `agent.voice` getter has no request context, so it throws when `voice` is a resolver. Use `agent.getVoice({ requestContext })` instead.
 
 ## Google Gemini Live (Realtime)
 

package/.docs/docs/voice/speech-to-text.md

@@ -78,4 +78,22 @@ const { text } = await agent.generate(
 console.log(`Recommendation: ${text}`)
 ```
 
-Check out the [Adding Voice to Agents](https://mastra.ai/docs/agents/adding-voice) documentation to learn how to use STT in an agent.
+## Transcribe an audio file
+
+The `listen()` method accepts a stream of audio data from a microphone or file. Use `createReadStream()` when you want to transcribe an audio file:
+
+```typescript
+import { createReadStream } from 'fs'
+import path from 'path'
+
+const audioFilePath = path.join(process.cwd(), 'agent.m4a')
+const audioStream = createReadStream(audioFilePath)
+
+const transcription = await agent.voice.listen(audioStream, {
+  filetype: 'm4a',
+})
+
+console.log(`Transcription: ${transcription}`)
+```
+
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).

package/.docs/docs/voice/text-to-speech.md

@@ -82,4 +82,24 @@ const readableStream = await voice.speak(text, {
 })
 ```
 
-Check out the [Adding Voice to Agents](https://mastra.ai/docs/agents/adding-voice) documentation to learn how to use TTS in an agent.
+## Save speech output
+
+The `speak()` method returns an audio stream. Pipe the stream to a file when you need to save generated speech for later playback or processing:
+
+```typescript
+import { createWriteStream } from 'fs'
+import path from 'path'
+
+const audio = await agent.voice.speak('Hello, world!')
+const filePath = path.join(process.cwd(), 'agent.mp3')
+const writer = createWriteStream(filePath)
+
+audio.pipe(writer)
+
+await new Promise<void>((resolve, reject) => {
+  writer.on('finish', () => resolve())
+  writer.on('error', reject)
+})
+```
+
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).

package/.docs/docs/workflows/control-flow.md

@@ -862,5 +862,5 @@ export const testWorkflow = createWorkflow({...})
 
 ## Related
 
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)

package/.docs/docs/workflows/error-handling.md

@@ -357,6 +357,6 @@ for await (const chunk of stream.stream) {
 ## Related
 
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Time Travel](https://mastra.ai/docs/workflows/time-travel)
 - [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)

package/.docs/docs/workflows/human-in-the-loop.md

@@ -214,4 +214,4 @@ const handleDelete = async () => {
 ## Related
 
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)

package/.docs/docs/workflows/overview.md

@@ -545,5 +545,5 @@ For a closer look at workflows, see our [Workflow Guide](https://mastra.ai/guide
 
 - [Workflow State](https://mastra.ai/docs/workflows/workflow-state)
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Error Handling](https://mastra.ai/docs/workflows/error-handling)

package/.docs/docs/workflows/snapshots.md

@@ -235,6 +235,6 @@ if (result.status === 'suspended') {
 ## Related
 
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Time Travel](https://mastra.ai/docs/workflows/time-travel)
 - [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)

package/.docs/docs/workflows/suspend-and-resume.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Suspend & resume
+# Suspend and resume
 
 Workflows can be paused at any step to collect additional data, wait for API callbacks, throttle costly operations, or request [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) input. When a workflow is suspended, its current execution state is saved as a snapshot. You can later resume the workflow from a [specific step ID](https://mastra.ai/docs/workflows/snapshots), restoring the exact state captured in that snapshot. [Snapshots](https://mastra.ai/docs/workflows/snapshots) are stored in your configured storage provider and persist across deployments and application restarts.
 

package/.docs/docs/workflows/time-travel.md

@@ -306,6 +306,6 @@ const result = await run.timeTravel({
 ## Related
 
 - [Snapshots](https://mastra.ai/docs/workflows/snapshots)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Error Handling](https://mastra.ai/docs/workflows/error-handling)
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)

package/.docs/docs/workflows/workflow-state.md

@@ -178,6 +178,6 @@ const parentWorkflow = createWorkflow({
 ## Related
 
 - [Workflows overview](https://mastra.ai/docs/workflows/overview)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Step Class](https://mastra.ai/reference/workflows/step)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)

package/.docs/guides/build-your-ui/copilotkit/channels.md

@@ -0,0 +1,76 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# CopilotKit channels
+
+The same Mastra agent that powers your in-app copilot can also run as a bot in messaging platforms. CopilotKit's bot layer connects your agent to Slack, Discord, Telegram, WhatsApp, and Microsoft Teams, with threads, tool calls, and human-in-the-loop approvals handled in the channel.
+
+> **Info:** The full setup lives in the [CopilotKit bot documentation](https://docs.copilotkit.ai/slack). This page shows how it fits together with a Mastra agent.
+
+## How it fits together
+
+Your Mastra agent stays where it is, exposed through `registerCopilotKit()` as described in [CopilotKit overview](https://mastra.ai/guides/build-your-ui/copilotkit/overview). The bot is a separate process built with `@copilotkit/bot`: you attach one or more platform adapters and point the bot at your agent. `createBot` takes an array of adapters, so a single bot can serve several platforms at once.
+
+```typescript
+import { createBot } from '@copilotkit/bot'
+import { slack } from '@copilotkit/bot-slack'
+
+const bot = createBot({
+  adapters: [
+    slack({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      appToken: process.env.SLACK_APP_TOKEN!,
+    }),
+  ],
+  // Point the bot at your agent.
+  agent: threadId => {
+    // ...connect to your CopilotKit runtime / Mastra agent
+  },
+})
+
+bot.onMention(async ({ thread }) => {
+  await thread.runAgent()
+})
+
+await bot.start()
+```
+
+Rich messages are written as JSX and rendered to each platform's native message format (Block Kit on Slack, for example), so an interactive card degrades gracefully where a platform has no equivalent.
+
+## Slack
+
+The [Slack quickstart](https://docs.copilotkit.ai/slack) takes you from zero to a bot you can `@`-mention in a channel, then adds an interactive button card. Slack runs over Socket Mode, which opens an outbound WebSocket to Slack, so no public URL or tunnel is required during development.
+
+Install the packages:
+
+**npm**:
+
+```bash
+npm install @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack
+```
+
+**pnpm**:
+
+```bash
+pnpm add @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack
+```
+
+**Yarn**:
+
+```bash
+yarn add @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack
+```
+
+**Bun**:
+
+```bash
+bun add @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack
+```
+
+Set the Slack credentials in your environment:
+
+- `SLACK_BOT_TOKEN`: Bot User OAuth token (`xoxb-...`)
+- `SLACK_APP_TOKEN`: App-level token with the `connections:write` scope (`xapp-...`)
+
+## Other platforms
+
+The bot adapters share one `@copilotkit/bot` API and differ only in what each platform natively supports. For Discord, Telegram, WhatsApp, and Microsoft Teams, set the relevant platform credentials and add the matching adapter to the `adapters` array. See the [CopilotKit bot documentation](https://docs.copilotkit.ai/slack) for platform-specific setup.