@mastra/mcp-docs-server 1.2.7-alpha.1 → 1.2.7-alpha.12

package/.docs/docs/studio/overview.md

@@ -4,7 +4,7 @@
 
 Studio provides an interactive UI for building, testing, and managing your agents, workflows, and tools. Run it locally during development, add [authentication](https://mastra.ai/docs/studio/auth), or [deploy it](https://mastra.ai/docs/studio/deployment) to production so your team can manage agents, monitor performance, and gain insights through built-in observability.
 
-[YouTube video player](https://www.youtube-nocookie.com/embed/ojGu6Bi4wYk)
+> **📹 Watch:** Watch [Mastra Studio overview](https://youtu.be/ojGu6Bi4wYk) for a short walkthrough of building, testing, and managing agents in Studio.
 
 ## Start Studio
 

package/.docs/docs/voice/livekit.md

@@ -162,6 +162,45 @@ export default createLiveKitWorker({
 
 See the [LiveKit turn detection docs](https://docs.livekit.io/agents/logic/turns/) for all options.
 
+## Per-call voices and transcription
+
+The top-level `stt` and `tts` options apply to every call. To pick them per call — one voice or language per tenant — set the `configuration.stt` and `configuration.tts` resolvers instead. Each resolver runs once per call with the dispatch metadata, request context, room name, and job context, and returns anything the matching top-level option accepts: a plugin instance or an inference model string. Return `undefined` to fall back to the top-level option.
+
+The following example gives each tenant its own text-to-speech voice, keyed off the `tenant` entry in the dispatch metadata:
+
+```typescript
+import * as cartesia from '@livekit/agents-plugin-cartesia'
+
+// One voice id per tenant, resolved from the dispatch metadata on each call.
+const tenantVoices: Record<string, string> = {
+  meridian: 'your-cartesia-voice-id-1',
+  coastal: 'your-cartesia-voice-id-2',
+}
+// The resolver runs during call setup, so cache plugin instances across calls.
+const ttsByVoice = new Map<string, cartesia.TTS>()
+
+export default createLiveKitWorker({
+  mastra,
+  agent: 'support',
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  configuration: {
+    tts: ({ requestContext }) => {
+      const voice = tenantVoices[requestContext?.tenant as string]
+      if (!voice) return undefined // fall back to the top-level `tts`
+      let tts = ttsByVoice.get(voice)
+      if (!tts) {
+        tts = new cartesia.TTS({ voice })
+        ttsByVoice.set(voice, tts)
+      }
+      return tts
+    },
+  },
+})
+```
+
+`configuration.stt` works the same way for per-call transcription, for example a different transcription model or language per tenant. The greeting has a matching per-call form: `configuration.greeting.text` accepts a resolver with the same call context, so one worker can open with each tenant's own phrasing.
+
 ## Memory and threads
 
 When the resolved Mastra agent has memory configured, each call becomes one memory thread:
@@ -172,7 +211,7 @@ When the resolved Mastra agent has memory configured, each call becomes one memo
 
 Each turn sends only the new user input; Mastra Memory supplies history, semantic recall, and working memory. Pin a session to an existing thread by passing `threadId` in the connection request body, which is useful for continuing a text conversation by voice. In Studio, starting a call from an open chat binds the call to that thread, and the transcript fills into the chat after each exchange.
 
-One caveat: when a user interrupts the agent, Mastra Memory stores the full generated reply even though the user only heard part of it. LiveKit's own transcript is truncated to what was spoken.
+When a user interrupts the agent, the in-flight generation aborts and nothing from that turn is persisted at that moment. LiveKit keeps the part the user actually heard in its transcript, and on the next turn the worker re-sends that heard-only fragment so the thread backfills to match the call. A user who hangs up right after interrupting leaves that final fragment unrecorded; see [interrupted turns](https://mastra.ai/reference/voice/livekit) for the details and a reconciliation recipe.
 
 ## Speak while tools run
 
@@ -189,13 +228,13 @@ export default createLiveKitWorker({
 })
 ```
 
-The phrase is spoken as part of the reply and appears in the transcript.
+The phrase is spoken as part of the reply and recorded in the transcript.
 
 ## Generate replies with a workflow
 
 By default the worker generates each reply with a Mastra agent. To run multi-step logic per turn (for example classify intent, route, call tools in sequence, then compose a reply), generate replies with a Mastra [workflow](https://mastra.ai/docs/workflows/overview) instead. Set `workflow` in place of `agent`.
 
-LiveKit still owns the audio loop and calls into Mastra once per turn, so the workflow runs to completion each turn. There is no suspend or resume, and no conversation state is carried between turns. Pass the transcript in through `workflowInput` so the workflow stays stateless:
+LiveKit still owns the audio loop and calls into Mastra once per turn, so the workflow runs to completion each turn. The workflow can't suspend or resume, and no conversation state carries between turns. Pass the transcript in through `workflowInput` so the workflow stays stateless:
 
 ```typescript
 import { createLiveKitWorker, chatContextToMessages } from '@mastra/livekit/worker'
@@ -233,6 +272,64 @@ const generateResponse = createStep({
 
 With a workflow, the worker doesn't persist turns automatically the way an agent's `stream()` does. Persist conversation history inside the workflow, or keep the LiveKit transcript as the source of truth and pass it in each turn.
 
+## Use Mastra as the LLM component
+
+`createLiveKitWorker()` owns the LiveKit session for you. To own the session yourself, use [`MastraLLM`](https://mastra.ai/reference/voice/livekit) instead: a standard LiveKit LLM plugin that puts a Mastra agent in the `llm` slot of your own `voice.AgentSession`. The Mastra app — agent loop, tools, memory, observability — runs on your Mastra server, and the worker reaches it over HTTP. The worker process needs no Mastra app, database, or model provider keys.
+
+```typescript
+import { fileURLToPath } from 'node:url'
+import { defineAgent, voice } from '@livekit/agents'
+import * as silero from '@livekit/agents-plugin-silero'
+import { MastraLLM } from '@mastra/livekit/plugin'
+import { runLiveKitWorker } from '@mastra/livekit/worker'
+
+export default defineAgent({
+  entry: async ctx => {
+    await ctx.connect()
+
+    const session = new voice.AgentSession({
+      llm: new MastraLLM({
+        remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'support' },
+        memory: { thread: ctx.room.name!, resource: 'user-7' },
+      }),
+      stt: 'deepgram/nova-3',
+      tts: 'cartesia/sonic-3',
+      vad: await silero.VAD.load(),
+      // Required with `memory`: LiveKit enables preemptive generation by default.
+      turnHandling: { preemptiveGeneration: { enabled: false } },
+    })
+
+    await session.start({
+      // These instructions never reach the Mastra agent; its own instructions apply.
+      agent: new voice.Agent({ instructions: 'Replies come from the Mastra agent.' }),
+      room: ctx.room,
+    })
+
+    session.say('Hi! How can I help you today?')
+  },
+})
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  runLiveKitWorker({ entry: import.meta.url, agentName: 'mastra-voice' })
+}
+```
+
+Both paths share the same reply pipeline underneath; choose by who should own the session:
+
+|                           | `createLiveKitWorker()`                                                                    | `MastraLLM`                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Session ownership         | The worker helper builds and manages the `AgentSession`                                    | Your code builds the session; every LiveKit option and hook is yours                        |
+| Where the Mastra app runs | In the worker process                                                                      | On your Mastra server, reached over HTTP (or in-process via `agent`)                        |
+| Worker process needs      | Your Mastra app, storage, and model provider keys                                          | Only the LiveKit SDK and network access to your server                                      |
+| Built-in conveniences     | Greeting, consent gating, agent-initiated hang-up, thread bootstrap, observability roll-up | Rebuild what you need with the [session helpers](https://mastra.ai/reference/voice/livekit) |
+| Best for                  | Fastest path to a working voice agent; Studio voice mode                                   | Existing LiveKit apps and full control over the session                                     |
+
+Tools stay on the Mastra agent and execute on the server; LiveKit-side tools passed to the session are ignored. Tool activity reaches the worker through `toolFeedback` (spoken filler), `onToolCall` (fires as each tool call starts), and `onTurnComplete` (fires after each reply with the text, tool calls, and token usage). Agent-initiated hang-up takes a few lines: pair `onToolCall` with [`runEndCall()`](https://mastra.ai/reference/voice/livekit).
+
+> **Warning:** Don't combine the `memory` option with LiveKit's `preemptiveGeneration`, which LiveKit enables by default in sessions you build yourself. A speculative turn that completes before LiveKit discards it persists a user message and a never-spoken reply to the thread. Set `turnHandling: { preemptiveGeneration: { enabled: false } }` as shown above, or run without `memory` and pass the full transcript each turn.
+
+`MastraLLM` also accepts an in-process Mastra `agent` instance — session ownership without a second deployment — or a custom `generate` function. The remote transport is available standalone as [`createRemoteAgentReplyGenerator()`](https://mastra.ai/reference/voice/livekit), which also plugs into `createLiveKitWorker`'s `generate` option to run the batteries-included worker against a remote server.
+
 ## Server-initiated sessions
 
 Use `dispatchVoiceSession()` to add a voice agent to a room from your own code, for example to join an existing room or to drive an outbound [SIP call](https://docs.livekit.io/sip/):
@@ -255,7 +352,7 @@ When the Mastra instance has [observability](https://mastra.ai/docs/observabilit
 - A child span for each LiveKit pipeline metric: speech-to-text, text-to-speech, end-of-utterance (turn detection), voice activity detection, and the model's time-to-first-token. These carry the latency and audio measurements that text traces can't show.
 - A per-model usage roll-up (token, character, and audio totals for the whole call) written to the span when the session ends.
 
-The worker is a separate process, so point storage at a backend that accepts concurrent writes from both the server and the worker. SQLite-backed [LibSQL](https://mastra.ai/reference/storage/libsql) works; single-writer stores do not. Traces, memory, and threads can share one store:
+The worker is a separate process, so point storage at a backend that accepts concurrent writes from both the server and the worker. SQLite-backed [LibSQL](https://mastra.ai/reference/storage/libsql) works; single-writer stores don't. Traces, memory, and threads can share one store:
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'

package/.docs/docs/workflows/agents-and-tools.md

@@ -57,7 +57,7 @@ export const testWorkflow = createWorkflow({})
   .commit()
 ```
 
-> **Info:** Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
+Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
 
 When no `structuredOutput` option is provided, Mastra agents use a default schema that expects a `prompt` string as input and returns a `text` string as output:
 
@@ -106,9 +106,7 @@ export const testWorkflow = createWorkflow({})
   .commit()
 ```
 
-The `structuredOutput.schema` option accepts any Standard JSON Schema. The agent will generate output conforming to this schema, and the step's `outputSchema` will be automatically set to match.
-
-> **Info:** Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more options like error handling strategies and streaming with structured output.
+The `structuredOutput.schema` option accepts any Standard JSON Schema. The agent will generate output conforming to this schema, and the step's `outputSchema` will be automatically set to match. Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more options like error handling strategies and streaming with structured output.
 
 ## Using tools in workflows
 
@@ -157,7 +155,7 @@ export const testWorkflow = createWorkflow({})
   .commit()
 ```
 
-> **Info:** Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
+Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
 
 ## Related
 

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

@@ -101,8 +101,6 @@ export const testWorkflow = createWorkflow({
   .commit()
 ```
 
-> **📹 Watch:** How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/GQJxve5Hki4)
-
 ### Output structure
 
 When steps run in parallel, the output is an object where each key is the step's `id` and the value is that step's output. This allows you to access each parallel step's result independently.
@@ -210,7 +208,7 @@ const writerStep = createStep({
 })
 ```
 
-> **Info:** Visit [Choosing the right pattern](#choosing-the-right-pattern) to understand when to use `.parallel()` vs `.foreach()`.
+Visit [Choosing the right pattern](#choosing-the-right-pattern) to understand when to use `.parallel()` vs `.foreach()`.
 
 ## Conditional logic with `.branch()`
 

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

@@ -10,8 +10,6 @@ Workflows let you define complex sequences of tasks using clear, structured step
 
 Use workflows for tasks that are clearly defined upfront and involve multiple steps with a specific execution order. They give you fine-grained control over how data flows and transforms between steps, and which primitives are called at each stage.
 
-> **Tip:** Watch an introduction to workflows, and how they compare to agents on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw).
-
 ## Core principles
 
 Mastra workflows operate using these principles:
@@ -103,7 +101,7 @@ const step1 = createStep({
 })
 ```
 
-> **Info:** Visit [`Step`](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
+Visit [`Step`](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
 
 ### Using agents and tools
 
@@ -177,7 +175,7 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
-> **Info:** Visit [Workflow Class](https://mastra.ai/reference/workflows/workflow) for a full list of configuration options.
+Visit [Workflow Class](https://mastra.ai/reference/workflows/workflow) for a full list of configuration options.
 
 ### Understanding control flow
 
@@ -214,7 +212,7 @@ const step1 = createStep({
 })
 ```
 
-> **Info:** Visit [Workflow State](https://mastra.ai/docs/workflows/workflow-state) for complete documentation on state schemas, initial state, persistence across suspend/resume, and nested workflows.
+Visit [Workflow State](https://mastra.ai/docs/workflows/workflow-state) for complete documentation on state schemas, initial state, persistence across suspend/resume, and nested workflows.
 
 ## Workflows as steps
 
@@ -535,7 +533,7 @@ const step1 = createStep({
 })
 ```
 
-> **Info:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
 
 > **Tip:** For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context).
 
@@ -546,4 +544,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 and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
-- [Error Handling](https://mastra.ai/docs/workflows/error-handling)
+- [Error Handling](https://mastra.ai/docs/workflows/error-handling)
+- 📹 [Agentic workflows with Mastra workshop](https://www.youtube.com/watch?v=HGt8pVPpX9g)

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

@@ -145,7 +145,7 @@ export const mastra = new Mastra({
 - [Upstash Storage](https://mastra.ai/reference/storage/upstash)
 - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
 - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
-- [More storage providers](https://mastra.ai/docs/memory/storage)
+- [More storage providers](https://mastra.ai/docs/storage/overview)
 
 ## Best practices
 

package/.docs/docs/workspace/overview.md

@@ -411,4 +411,5 @@ External providers may perform additional setup like establishing connections or
 - [LSP inspection](https://mastra.ai/docs/workspace/lsp)
 - [Skills](https://mastra.ai/docs/workspace/skills)
 - [Search and indexing](https://mastra.ai/docs/workspace/search)
-- [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)
+- [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)
+- 📹 [Introduction to Mastra Workspaces workshop](https://www.youtube.com/watch?v=QcQLiYlJuNQ)

package/.docs/docs/workspace/sandbox.md

@@ -15,6 +15,8 @@ A sandbox provider executes commands in a controlled environment:
 - **Timeouts**: Prevent long-running commands from hanging
 - **Isolation**: Optional OS-level sandboxing for security
 
+> **📹 Watch:** Watch [Mastra remote sandboxes overview](https://www.youtube.com/watch?v=Ix2X-sjVXjw) to see how remote sandboxes give agents an isolated computer to work in.
+
 ## Supported providers
 
 - [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox): Executes commands on the local machine

package/.docs/guides/build-your-ui/assistant-ui.md

@@ -6,7 +6,7 @@
 
 > **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/integrations/frameworks/mastra/full-stack) on Assistant UI's documentation site.
 
-> **Tip:** Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of Assistant UI integrated with Mastra.
+Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of Assistant UI integrated with Mastra.
 
 ## Integration guide
 

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

@@ -8,7 +8,7 @@ The same Mastra agent that powers your in-app copilot can also run as a bot in m
 
 ## 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.
+Your Mastra agent stays where it's, 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'

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

@@ -37,7 +37,7 @@ export const weatherAgent = new Agent({
 })
 ```
 
-On the frontend, register a renderer for the tool by name with `useRenderTool`. It is render-only (it does not execute the tool); the `render` function receives the tool call's `status` and, once the agent returns, its `result`:
+On the frontend, register a renderer for the tool by name with `useRenderTool`. It's render-only (it doesn't execute the tool); the `render` function receives the tool call's `status` and, once the agent returns, its `result`:
 
 ```tsx
 import { z } from 'zod'
@@ -152,7 +152,7 @@ The catalog defines the primitives (their schemas) and the renderers (how each p
 
 At the far end of the spectrum, the agent owns the entire surface: the UI is invented elsewhere and sandboxed in your app. CopilotKit supports this through **MCP Apps**, where an MCP server ships UI that renders inside your application. This tier trades determinism for novelty and is the most experimental point on the spectrum.
 
-The path of least resistance keeps the frontend untouched: your existing `<CopilotKit>` provider is enough. On the backend, point `registerCopilotKit()` at one or more MCP servers with the `mcpApps` option (it is forwarded to the CopilotKit runtime):
+The path of least resistance keeps the frontend untouched: your existing `<CopilotKit>` provider is enough. On the backend, point `registerCopilotKit()` at one or more MCP servers with the `mcpApps` option (it's forwarded to the CopilotKit runtime):
 
 ```typescript
 registerCopilotKit({

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

@@ -10,7 +10,7 @@ Visit the [CopilotKit documentation](https://docs.copilotkit.ai/) to learn more
 
 > **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart) guide.
 
-> **Tip:** Visit Mastra's ["UI Dojo"](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
+Visit Mastra's ["UI Dojo"](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
 
 ## Integration guide
 

package/.docs/guides/concepts/streaming.md

@@ -29,7 +29,7 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-> **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
+Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
 > **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
 
@@ -101,7 +101,7 @@ for await (const chunk of stream) {
 }
 ```
 
-> **Info:** Visit [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream) for more information.
+Visit [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream) for more information.
 
 ### Output from `Run.stream()`
 
@@ -160,7 +160,7 @@ for await (const chunk of stream) {
 }
 ```
 
-> **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
+Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
 ### Example agent output
 

package/.docs/guides/getting-started/quickstart.md

@@ -8,6 +8,8 @@ The `create mastra` CLI command is the quickest way to get started. It walks you
 
 If you need more control over the setup, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). You can also use [`mastra init`](https://mastra.ai/reference/cli/mastra) for existing projects.
 
+> **📹 Watch:** Watch [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
+
 ## Before you begin
 
 - You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
@@ -50,7 +52,7 @@ The wizard creates a new directory for your project with a `src/mastra` folder c
 - `workflows/weather-workflow.ts`: A workflow that runs the weather agent
 - `scorers/weather-scorer.ts`: A scorer to evaluate the weather agent's responses
 
-Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/getting-started/build-with-ai) or the [MCP Docs Server](https://mastra.ai/docs/getting-started/build-with-ai) installed.
+Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/getting-started/build-with-ai) or the [MCP Docs Server](https://mastra.ai/docs/getting-started/build-with-ai) installed. Learn more about Mastra's [project structure](https://mastra.ai/reference/project-structure).
 
 > **Tip:** You can use [flags](https://mastra.ai/reference/cli/create-mastra) with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates).
 
@@ -58,7 +60,7 @@ Depending on your choices, you'll also end up with [Mastra Skills](https://mastr
 
 Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at [localhost:4111](http://localhost:4111).
 
-Try asking about the weather. If your API key is set up correctly, you'll get a response:
+Try asking about the weather. If your API key is set up correctly, you'll get a response in Studio.
 
 [Studio](https://mastra.ai/docs/studio/overview) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your app using the guides below.
 

package/.docs/guides/guide/chef-michel.md

@@ -6,8 +6,6 @@ In this guide, you'll create a "Chef Assistant" agent that helps users cook meal
 
 You'll learn how to create the agent and register it with Mastra. Next, you'll interact with the agent through your terminal and get to know different response formats. Lastly, you'll access the agent through Mastra's local API endpoints.
 
-[YouTube video player](https://www.youtube-nocookie.com/embed/_tZhOqHCrF0)
-
 ## Prerequisites
 
 - Node.js `v22.13.0` or later installed

package/.docs/guides/guide/slack-assistant.md

@@ -182,12 +182,12 @@ You can extend this agent to:
 
 - [Deploy your application](https://mastra.ai/docs/deployment/overview) and update the Slack **Request URL** to your production endpoint
 - Add more adapters (Discord, Telegram) to the same agent so it responds on multiple platforms
-- Configure [multimodal content](https://mastra.ai/docs/agents/channels) to let your agent process images, video, and audio shared in chat
+- Configure [multimodal content](https://mastra.ai/docs/capabilities/channels/overview) to let your agent process images, video, and audio shared in chat
 - Add [tools](https://mastra.ai/docs/agents/using-tools) to give the agent access to external APIs and data
 
 Learn more:
 
-- [Channels overview](https://mastra.ai/docs/agents/channels)
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
 - [Studio](https://mastra.ai/docs/studio/overview)
 - [Deployment overview](https://mastra.ai/docs/deployment/overview)
 - [Chat SDK adapter docs](https://chat-sdk.dev)

package/.docs/guides/guide/stock-agent.md

@@ -4,8 +4,6 @@
 
 In this guide, you're going to create an agent that fetches the last day's closing stock price for a given symbol. You'll learn how to create a tool, add it to an agent, and use the agent to fetch stock prices.
 
-[YouTube video player](https://www.youtube-nocookie.com/embed/rIaZ4l7y9wo)
-
 ## Prerequisites
 
 - Node.js `v22.13.0` or later installed

package/.docs/models/embeddings.md

@@ -37,17 +37,136 @@ const embedder = new ModelRouterEmbeddingModel("openai/text-embedding-3-small");
 const embedder = new ModelRouterEmbeddingModel("google/gemini-embedding-001");
 ```
 
+### VoyageAI
+
+VoyageAI provides specialized embedding models optimized for retrieval tasks. These models are available as standalone packages:
+
+**npm**:
+
+```bash
+npm install @mastra/voyageai
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/voyageai
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/voyageai
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/voyageai
+```
+
+**Available models:**
+
+- `voyage-4-large` - 1024 dimensions (default), supports 256-2048 dimensions, best general-purpose and multilingual retrieval quality (120k max tokens per batch)
+- `voyage-4` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for general-purpose and multilingual retrieval (320k max tokens per batch)
+- `voyage-4-lite` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for latency and cost (1M max tokens per batch)
+- `voyage-code-3` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for code retrieval
+- `voyage-finance-2` - 1024 dimensions, optimized for finance retrieval and RAG
+- `voyage-law-2` - 1024 dimensions, optimized for legal retrieval and RAG (16k context)
+- `voyage-3-large` - 1024 dimensions (default), supports 256-2048 dimensions (previous generation)
+- `voyage-3.5` - 1024 dimensions (default), supports 256-2048 dimensions (previous generation)
+- `voyage-3.5-lite` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for latency and cost (previous generation)
+- `voyage-multimodal-3.5` - 1024 dimensions, supports text + images
+
+```typescript
+import { voyage, voyageEmbedding } from "@mastra/voyageai";
+
+// Use default model (voyage-3.5)
+const { embeddings } = await voyage.doEmbed({
+  values: ["Hello world"],
+});
+
+// Use specific model (voyage-3-large)
+const largeEmbeddings = await voyage.large.doEmbed({
+  values: ["More complex content"],
+});
+
+// Custom configuration
+const customModel = voyageEmbedding({
+  model: "voyage-3.5",
+  inputType: "query", // or 'document'
+  outputDimension: 512, // 256, 512, 1024, or 2048
+});
+
+const { embeddings: customEmbeddings } = await customModel.doEmbed({
+  values: ["Custom configuration example"],
+});
+```
+
+**VoyageAI with MongoDB:**
+
+VoyageAI works seamlessly with MongoDB Atlas Vector Search:
+
+```typescript
+import { voyage } from "@mastra/voyageai";
+import { MongoDBVector } from "@mastra/mongodb";
+
+const mongoVector = new MongoDBVector({
+  id: "mongodb-vector",
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+});
+
+// Create index matching VoyageAI dimensions
+await mongoVector.createIndex({
+  indexName: "documents",
+  dimension: 1024, // voyage-3.5 default
+});
+
+// Generate and store embeddings
+const { embeddings } = await voyage.doEmbed({
+  values: chunks.map((chunk) => chunk.text),
+});
+
+await mongoVector.upsert({
+  indexName: "documents",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+**Multimodal embeddings (text + images):**
+
+```typescript
+import { voyage } from "@mastra/voyageai";
+
+const { embeddings } = await voyage.multimodal.doEmbed({
+  values: [
+    {
+      content: [
+        { type: "text", text: "Product description" },
+        { type: "image_url", image_url: "https://example.com/image.jpg" },
+      ],
+    },
+  ],
+});
+```
+
+For more details, see the [MongoDB + VoyageAI integration guide](https://mastra.ai/reference/vectors/mongodb).
+
 ## Authentication
 
 The model router automatically detects API keys from environment variables:
 
 - **OpenAI**: `OPENAI_API_KEY`
 - **Google**: `GOOGLE_API_KEY` (falls back to `GOOGLE_GENERATIVE_AI_API_KEY`)
+- **VoyageAI**: `VOYAGE_API_KEY`
 
 ```bash
 # .env
 OPENAI_API_KEY=sk-...
 GOOGLE_API_KEY=...
+VOYAGE_API_KEY=pa-...
 ```
 
 ## Custom Providers

package/.docs/models/environment-variables.md

@@ -31,12 +31,14 @@ List of required environment variables for each model provider and gateway suppo
 | [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)              | `cloudflare-workers-ai/*`  | `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_KEY`                                                         |
 | [Cortecs](https://mastra.ai/models/providers/cortecs)                                          | `cortecs/*`                | `CORTECS_API_KEY`                                                                                     |
 | [CrofAI](https://mastra.ai/models/providers/crof)                                              | `crof/*`                   | `CROF_API_KEY`                                                                                        |
+| [CrossModel](https://mastra.ai/models/providers/crossmodel)                                    | `crossmodel/*`             | `CROSSMODEL_API_KEY`                                                                                  |
 | [D.Run (China)](https://mastra.ai/models/providers/drun)                                       | `drun/*`                   | `DRUN_API_KEY`                                                                                        |
 | [Databricks](https://mastra.ai/models/providers/databricks)                                    | `databricks/*`             | `DATABRICKS_HOST`, `DATABRICKS_TOKEN`                                                                 |
 | [Deep Infra](https://mastra.ai/models/providers/deepinfra)                                     | `deepinfra/*`              | `DEEPINFRA_API_KEY`                                                                                   |
 | [DeepSeek](https://mastra.ai/models/providers/deepseek)                                        | `deepseek/*`               | `DEEPSEEK_API_KEY`                                                                                    |
 | [DigitalOcean](https://mastra.ai/models/providers/digitalocean)                                | `digitalocean/*`           | `DIGITALOCEAN_ACCESS_TOKEN`                                                                           |
 | [DInference](https://mastra.ai/models/providers/dinference)                                    | `dinference/*`             | `DINFERENCE_API_KEY`                                                                                  |
+| [EmpirioLabs AI](https://mastra.ai/models/providers/empiriolabs)                               | `empiriolabs/*`            | `EMPIRIOLABS_API_KEY`                                                                                 |
 | [evroc](https://mastra.ai/models/providers/evroc)                                              | `evroc/*`                  | `EVROC_API_KEY`                                                                                       |
 | [FastRouter](https://mastra.ai/models/providers/fastrouter)                                    | `fastrouter/*`             | `FASTROUTER_API_KEY`                                                                                  |
 | [Fireworks AI](https://mastra.ai/models/providers/fireworks-ai)                                | `fireworks-ai/*`           | `FIREWORKS_API_KEY`                                                                                   |
@@ -68,6 +70,7 @@ List of required environment variables for each model provider and gateway suppo
 | [LongCat](https://mastra.ai/models/providers/longcat)                                          | `longcat/*`                | `LONGCAT_API_KEY`                                                                                     |
 | [LucidQuery](https://mastra.ai/models/providers/lucidquery)                                    | `lucidquery/*`             | `LUCIDQUERY_API_KEY`                                                                                  |
 | [Meganova](https://mastra.ai/models/providers/meganova)                                        | `meganova/*`               | `MEGANOVA_API_KEY`                                                                                    |
+| [Meta](https://mastra.ai/models/providers/meta)                                                | `meta/*`                   | `META_MODEL_API_KEY`                                                                                  |
 | [MiniMax (minimax.io)](https://mastra.ai/models/providers/minimax)                             | `minimax/*`                | `MINIMAX_API_KEY`                                                                                     |
 | [MiniMax (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn)                        | `minimax-cn/*`             | `MINIMAX_API_KEY`                                                                                     |
 | [MiniMax Token Plan (minimax.io)](https://mastra.ai/models/providers/minimax-coding-plan)      | `minimax-coding-plan/*`    | `MINIMAX_API_KEY`                                                                                     |
@@ -75,6 +78,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Mistral](https://mastra.ai/models/providers/mistral)                                          | `mistral/*`                | `MISTRAL_API_KEY`                                                                                     |
 | [Mixlayer](https://mastra.ai/models/providers/mixlayer)                                        | `mixlayer/*`               | `MIXLAYER_API_KEY`                                                                                    |
 | [Moark](https://mastra.ai/models/providers/moark)                                              | `moark/*`                  | `MOARK_API_KEY`                                                                                       |
+| [Model Oracle AI](https://mastra.ai/models/providers/model-oracle-ai)                          | `model-oracle-ai/*`        | `MODEL_ORACLE_API_KEY`                                                                                |
 | [ModelScope](https://mastra.ai/models/providers/modelscope)                                    | `modelscope/*`             | `MODELSCOPE_API_KEY`                                                                                  |
 | [Moonshot AI](https://mastra.ai/models/providers/moonshotai)                                   | `moonshotai/*`             | `MOONSHOT_API_KEY`                                                                                    |
 | [Moonshot AI (China)](https://mastra.ai/models/providers/moonshotai-cn)                        | `moonshotai-cn/*`          | `MOONSHOT_API_KEY`                                                                                    |
@@ -95,6 +99,7 @@ List of required environment variables for each model provider and gateway suppo
 | [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)                           | `ovhcloud/*`               | `OVHCLOUD_API_KEY`                                                                                    |
 | [Perplexity](https://mastra.ai/models/providers/perplexity)                                    | `perplexity/*`             | `PERPLEXITY_API_KEY`                                                                                  |
 | [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)                        | `perplexity-agent/*`       | `PERPLEXITY_API_KEY`                                                                                  |
+| [Pioneer](https://mastra.ai/models/providers/pioneer)                                          | `pioneer/*`                | `PIONEER_API_KEY`                                                                                     |
 | [Poe](https://mastra.ai/models/providers/poe)                                                  | `poe/*`                    | `POE_API_KEY`                                                                                         |
 | [Poolside](https://mastra.ai/models/providers/poolside)                                        | `poolside/*`               | `POOLSIDE_API_KEY`                                                                                    |
 | [Privatemode AI](https://mastra.ai/models/providers/privatemode-ai)                            | `privatemode-ai/*`         | `PRIVATEMODE_API_KEY`                                                                                 |
@@ -124,6 +129,7 @@ List of required environment variables for each model provider and gateway suppo
 | [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)                              | `trustedrouter/*`          | `TRUSTEDROUTER_API_KEY`                                                                               |
 | [Umans AI](https://mastra.ai/models/providers/umans-ai)                                        | `umans-ai/*`               | `UMANS_AI_API_KEY`                                                                                    |
 | [Umans AI Coding Plan](https://mastra.ai/models/providers/umans-ai-coding-plan)                | `umans-ai-coding-plan/*`   | `UMANS_AI_CODING_PLAN_API_KEY`                                                                        |
+| [UnoRouter](https://mastra.ai/models/providers/unorouter)                                      | `unorouter/*`              | `UNOROUTER_API_KEY`                                                                                   |
 | [Upstage](https://mastra.ai/models/providers/upstage)                                          | `upstage/*`                | `UPSTAGE_API_KEY`                                                                                     |
 | [Vivgrid](https://mastra.ai/models/providers/vivgrid)                                          | `vivgrid/*`                | `VIVGRID_API_KEY`                                                                                     |
 | [Vultr](https://mastra.ai/models/providers/vultr)                                              | `vultr/*`                  | `VULTR_API_KEY`                                                                                       |
@@ -138,6 +144,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Z.AI](https://mastra.ai/models/providers/zai)                                                 | `zai/*`                    | `ZHIPU_API_KEY`                                                                                       |
 | [Z.AI Coding Plan](https://mastra.ai/models/providers/zai-coding-plan)                         | `zai-coding-plan/*`        | `ZHIPU_API_KEY`                                                                                       |
 | [Zeldoc](https://mastra.ai/models/providers/zeldoc)                                            | `zeldoc/*`                 | `ZELDOC_API_KEY`                                                                                      |
+| [Zenifra](https://mastra.ai/models/providers/zenifra)                                          | `zenifra/*`                | `ZENIFRA_AI_KEY`                                                                                      |
 | [ZenMux](https://mastra.ai/models/providers/zenmux)                                            | `zenmux/*`                 | `ZENMUX_API_KEY`                                                                                      |
 | [Zhipu AI](https://mastra.ai/models/providers/zhipuai)                                         | `zhipuai/*`                | `ZHIPU_API_KEY`                                                                                       |
 | [Zhipu AI Coding Plan](https://mastra.ai/models/providers/zhipuai-coding-plan)                 | `zhipuai-coding-plan/*`    | `ZHIPU_API_KEY`                                                                                       |