@mastra/mcp-docs-server 1.2.11 → 1.2.12-alpha.0

package/.docs/guides/guide/research-coordinator.md

@@ -2,9 +2,9 @@
 
 # Build a research coordinator with supervisor agents
 
-In this guide, you'll build a research coordinator that orchestrates multiple specialized agents using supervisor agents. The coordinator will delegate research tasks to a research agent and writing tasks to a writing agent, then synthesize the results into a comprehensive report.
+In this guide, you'll build a research coordinator that orchestrates multiple specialized agents using supervisor agents. The coordinator will delegate research tasks to a research agent and writing tasks to a writing agent, then synthesize the results into a detailed report.
 
-You'll learn how to set up subagents with clear roles, configure a supervisor agent to coordinate them, use delegation hooks to control execution, and validate task completion with scorers.
+You'll set up subagents with clear roles and configure a supervisor agent to coordinate them. You'll also use delegation hooks to control execution and scorers to validate task completion.
 
 ## Prerequisites
 
@@ -172,7 +172,7 @@ export const mastra = new Mastra({
 The `defaultOptions` on the supervisor agent configure delegation hooks and iteration monitoring:
 
 - `onDelegationStart` modifies the research agent's prompt to request recent data
-- `onDelegationComplete` logs completion, bails on errors, and provides feedback
+- `onDelegationComplete` logs completion and stops on errors, then provides feedback
 - `messageFilter` limits context to the last 10 messages for efficiency
 - `onIterationComplete` monitors progress after each iteration
 

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

@@ -160,7 +160,7 @@ Select **Save Changes**. Slack requires you to reinstall the app after changing
 
 ## Test the agent
 
-Before testing with Slack, you can refine your agent's behavior in [Studio](https://mastra.ai/docs/studio/overview). Open <http://localhost:4111/> to chat with your agent directly, adjust its instructions, and inspect traces to see how responses are generated.
+Before testing with Slack, you can refine your agent's behavior in [Studio](https://mastra.ai/docs/studio/overview). Open <http://localhost:4111/> to chat with your agent and adjust its instructions. Inspect traces to see how responses are generated.
 
 Once you're happy with the agent's responses, test the Slack integration. Invite the bot to a channel in Slack:
 

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

@@ -2,7 +2,7 @@
 
 # Building an AI stock agent
 
-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.
+In this guide, you'll create an agent that fetches the previous day's closing stock price for a symbol. You'll create a tool and add it to an agent, then use the agent to fetch stock prices.
 
 ## Prerequisites
 

package/.docs/guides/index.md

@@ -2,7 +2,7 @@
 
 # Mastra Guides
 
-Mastra offers a variety of guides to help you build and work with Mastra, from building agents and workflows to using the Mastra SDK and API, and implementing different UI frameworks. Explore the guides below to find the resources you need to get started and build with Mastra.
+Mastra offers guides for building agents and workflows, using the Mastra SDK and API, and implementing different UI frameworks. Explore these guides to find the resources you need to get started and build with Mastra.
 
 ## New project
 

package/.docs/guides/migrations/ai-sdk-v4-to-v5.md

@@ -13,7 +13,7 @@ This guide covers only the Mastra-specific aspects of the migration.
 
 ## Memory and storage
 
-Mastra automatically handles AI SDK v4 data using its internal `MessageList` class, which manages format conversion—including v4 to v5. No database migrations are required; your existing messages are translated on the fly and continue working after you upgrade.
+Mastra automatically handles AI SDK v4 data using its internal `MessageList` class, which manages format conversion, including v4 to v5. No database migrations are required. Your existing messages are translated on the fly and continue working after you upgrade.
 
 ## Message format conversion
 

package/.docs/guides/migrations/mastra-cloud.md

@@ -60,7 +60,7 @@ The Mastra platform replaces Mastra Cloud with separate Studio and Server produc
 
 Mastra Cloud provided a managed libSQL database, backed by [Turso](https://turso.tech). The Mastra platform doesn't host a database for you, so you need to point your storage at an externally hosted instance.
 
-If you were already using a hosted database ("bring your own"), no changes are needed. Ensure the connection string is set as an environment variable in the dashboard rather than hardcoded.
+If you were already using a hosted database ("bring your own"), keep the existing database configuration. Ensure the connection string is set as an environment variable in the dashboard rather than hardcoded.
 
 If you were using Cloud Store, follow the steps below to export your data and load it into a new libSQL database that you control.
 
@@ -68,7 +68,7 @@ If you were using Cloud Store, follow the steps below to export your data and lo
 
 You can export your Cloud Store data in two ways: download it from the dashboard, or create a manual dump with the Turso CLI.
 
-#### Option A — Export from the dashboard (recommended)
+#### Option A: Export from the dashboard (recommended)
 
 Open your project in the [Mastra dashboard](https://projects.mastra.ai) and navigate to **Runtime → Settings → Storage**. Click the **Export Database** button. The dashboard generates a full `.sql` dump of your Cloud Store and downloads it directly to your Downloads folder.
 
@@ -80,7 +80,7 @@ sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql
 
 You now have a portable `mydb.db` file you can inspect locally, back up, or use as the source for the new database in the steps that follow.
 
-#### Option B — Export via the Turso CLI
+#### Option B: Export via the Turso CLI
 
 If you prefer to work from the command line, or need to script the export, you can dump the database directly using the [Turso CLI](https://docs.turso.tech/cli). This approach requires the database URL and an auth token, both surfaced in the dashboard.
 
@@ -269,7 +269,7 @@ Deploy your hosted Studio instance:
 mastra studio deploy
 ```
 
-The CLI builds your project, uploads the artifact, and deploys it. On first deploy, a `.mastra-project.json` file is created to link your local project to the platform. Commit this file to your repository.
+The CLI builds your project and uploads the artifact before deploying it. On first deploy, a `.mastra-project.json` file is created to link your local project to the platform. Commit this file to your repository.
 
 A local env file is optional. When a `.env` or `.env.*` file is present in the project directory, the deploy bundles its environment variables.
 
@@ -283,14 +283,14 @@ See [Studio deployment](https://mastra.ai/docs/studio/deployment) for details.
 
 ### Multiple environments
 
-A single Mastra platform project runs the same codebase across multiple named [environments](https://mastra.ai/docs/mastra-platform/environments), such as `production` and `staging`. Deploy to each with the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command:
+A single Mastra platform project runs the same codebase across multiple [environments](https://mastra.ai/docs/mastra-platform/environments), such as `production` and `staging`. Deploy to each with the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command:
 
 ```bash
 mastra deploy --env production --yes
 mastra deploy --env staging --env-file .env.staging --yes
 ```
 
-Each environment gets its own URL, its own environment variables, and its own deploy history.
+Each environment has a dedicated URL and environment variables, along with a separate deploy history.
 
 ## Deploy Server (optional)
 

package/.docs/guides/migrations/network-to-supervisor.md

@@ -4,11 +4,11 @@
 
 Supervisor agents using `Agent.stream()` and `Agent.generate()` are the recommended approach for coordinating multiple agents, replacing the older `.network()` API. This guide walks you through each step of the migration.
 
-> **.network() Deprecation:** `.network()` is deprecated and will be removed in a future release. While existing code will continue to work until then, no new features will be added to it. Migrate to supervisor agents as soon as possible.
+> **.network() Deprecation:** `.network()` is deprecated and will be removed in a future release. Existing code will continue to work until then, but development now focuses on supervisor agents. Migrate to supervisor agents as soon as possible.
 
 ## Replace `.network()` with `.stream()` or `.generate()`
 
-The core change is replacing `.network()` calls with `.stream()` (for streaming) or `.generate()` (for non-streaming). The agent configuration stays the same -- you still define `agents`, `workflows`, `tools`, and `memory` on the agent. The difference is how you call it and how you process the results.
+The core change is replacing `.network()` calls with `.stream()` (for streaming) or `.generate()` (for non-streaming). The agent configuration stays the same. You still define `agents`, `workflows`, `tools`, and `memory` on the agent. The difference is how you call it and how you process the results.
 
 With `.network()`, you iterated over custom event types like `network-execution-event-step-finish`. With `.stream()`, you use the standard `textStream` or `fullStream` iterators.
 
@@ -50,9 +50,9 @@ console.log(result.text)
 
 ## Write clear supervisor instructions
 
-With `.network()`, the routing agent relied on generic instructions and primitive descriptions to decide what to call. Supervisor agents work the same way, but clear and specific instructions significantly improve delegation accuracy.
+With `.network()`, the routing agent relied on generic instructions and primitive descriptions to decide what to call. Supervisor agents work the same way, but clear and specific instructions improve delegation accuracy.
 
-Your supervisor's `instructions` should specify what resources are available, when to use each one, how to coordinate them, and when the task is complete.
+Your supervisor's `instructions` should identify the available resources and when to use each one. They should also explain how to coordinate those resources and recognize when the task is complete.
 
 **Before:**
 
@@ -92,7 +92,7 @@ Success criteria:
 
 ## Add descriptions to subagents
 
-Each subagent should have a `description` field that explains what it does, what format it returns, and when it should be used. The supervisor uses these descriptions to decide which agent to delegate to.
+Each subagent should have a `description` field that explains its purpose and return format. The description should also state when to use the subagent. The supervisor uses these descriptions to decide which agent to delegate to.
 
 ```typescript
 const researchAgent = new Agent({
@@ -129,7 +129,7 @@ If you were handling specific `.network()` events, update them to use the standa
 
 Supervisor agents let you hook into the delegation lifecycle to monitor, modify, or reject delegations. These hooks can be configured in the agent's `defaultOptions` or passed per-call.
 
-`onDelegationStart` is called before the supervisor delegates to a subagent. You can modify the prompt, limit the subagent's steps, or reject the delegation entirely:
+`onDelegationStart` is called before the supervisor delegates to a subagent. You can modify the prompt or limit the subagent's steps. The hook can also reject the delegation entirely:
 
 ```typescript
 const stream = await supervisorAgent.stream('Research AI in education', {
@@ -159,7 +159,7 @@ const stream = await supervisorAgent.stream('Research AI in education', {
 })
 ```
 
-`onDelegationComplete` is called after a delegation finishes. You can inspect the result, call `context.bail()` to stop the supervisor loop, and return feedback that gets saved to the supervisor's memory:
+`onDelegationComplete` is called after a delegation finishes. Inspect the result and call `context.bail()` when the supervisor loop should stop. You can also return feedback that gets saved to the supervisor's memory:
 
 ```typescript
 const stream = await supervisorAgent.stream('Research AI in education', {
@@ -179,7 +179,7 @@ const stream = await supervisorAgent.stream('Research AI in education', {
 
 ## Add message filtering
 
-By default, subagents receive the full conversation context from the supervisor. Use `messageFilter` to control what messages are shared -- for example, to remove sensitive data or limit the number of messages:
+By default, subagents receive the full conversation context from the supervisor. Use `messageFilter` to control what messages are shared. For example, remove sensitive data or limit the number of messages:
 
 ```typescript
 const stream = await supervisorAgent.stream('Research AI in education', {
@@ -200,7 +200,7 @@ const stream = await supervisorAgent.stream('Research AI in education', {
 
 ## Add iteration monitoring
 
-`onIterationComplete` is called after each iteration of the supervisor loop. You can use it to log progress, provide feedback to guide the agent, or stop execution early:
+`onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress or provide feedback that guides the agent. The hook can also stop execution early:
 
 ```typescript
 const stream = await supervisorAgent.stream('Research AI in education', {

package/.docs/guides/migrations/upgrade-to-v1/agent.md

@@ -45,7 +45,7 @@ To migrate, replace all calls to `mastra.getAgents()` with `mastra.listAgents()`
 
 ### `RuntimeContext` to `RequestContext`
 
-The `RuntimeContext` class has been renamed to `RequestContext` throughout the codebase. This change provides clearer naming that better describes its purpose as request-specific data and aligns with web framework conventions.
+The `RuntimeContext` class has been renamed to `RequestContext` throughout the codebase. The new name identifies the class as request-specific data and matches web framework conventions.
 
 To migrate, update all imports and parameter names from `RuntimeContext`/`runtimeContext` to `RequestContext`/`requestContext`.
 
@@ -91,7 +91,7 @@ To migrate, replace property access with the corresponding getter methods.
 
 ### Voice methods moved to `agent.voice` namespace
 
-Voice-related methods have been moved from the Agent class to the `agent.voice` namespace. This change provides better organization and clearer separation of concerns.
+Voice-related methods have moved from the Agent class to the `agent.voice` namespace, which groups the voice APIs together.
 
 To migrate, update voice method calls to use the `agent.voice` namespace.
 
@@ -112,7 +112,7 @@ To migrate, update voice method calls to use the `agent.voice` namespace.
 
 ### `agent.fetchMemory()` to `(await agent.getMemory()).recall()`
 
-The `fetchMemory()` method has been replaced with a more explicit API. This change provides better clarity about the asynchronous nature of memory access.
+The `fetchMemory()` method has been replaced with an API that makes asynchronous memory access explicit.
 
 To migrate, replace `fetchMemory()` calls with the new API.
 
@@ -167,7 +167,7 @@ Only update your imports if you want to standardize on one Zod version across yo
 
 ### Default options method renames for AI SDK versions
 
-Default options methods have been renamed to clarify legacy (AI SDK v4) vs new (AI SDK v5+) APIs. This change helps developers understand which AI SDK version they're targeting.
+Default options methods have been renamed to distinguish legacy (AI SDK v4) APIs from AI SDK v5+ APIs. The method name now indicates which AI SDK version it targets.
 
 To migrate, update method names based on which AI SDK version you're using.
 
@@ -184,7 +184,7 @@ To migrate, update method names based on which AI SDK version you're using.
 
 ### `modelSettings.abortSignal` to top-level `abortSignal`
 
-The `abortSignal` option has been moved from `modelSettings` to the top level of stream/generate options. This change provides a clearer separation between model-specific settings and execution control.
+The `abortSignal` option has moved from `modelSettings` to the top level of stream and generate options. Execution control now sits outside model-specific settings.
 
 To migrate, move `abortSignal` from `modelSettings` to the top level.
 

package/.docs/guides/migrations/upgrade-to-v1/cli.md

@@ -14,7 +14,7 @@ A new `mastra migrate` command helps run database migrations when upgrading Mast
 npx mastra migrate
 ```
 
-The command bundles your project, connects to your configured storage, and runs any necessary migrations. Currently supports migrating duplicate spans entries that may prevent unique constraint creation.
+The command bundles your project and connects to your configured storage before running any necessary migrations. It currently supports migrating duplicate span entries that may prevent unique constraint creation.
 
 See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details on when this migration is needed.
 

package/.docs/guides/migrations/upgrade-to-v1/client.md

@@ -2,7 +2,7 @@
 
 # Client SDK
 
-Client SDK changes align with server-side API updates including renamed utilities, updated pagination, and type naming conventions.
+Client SDK changes align with server-side API updates, including utility renames, updated pagination, and type naming conventions.
 
 ## Changed
 
@@ -126,7 +126,7 @@ To migrate, update type imports to use the new naming pattern.
 
 ### Pagination parameters from `offset/limit` to `page/perPage`
 
-All client SDK methods that used `offset/limit` now use `page/perPage`. This change provides a more intuitive pagination model aligned with web pagination patterns.
+All client SDK methods that used `offset/limit` now use `page/perPage`, matching page-based web pagination.
 
 To migrate, update pagination parameters in all client SDK method calls. Example:
 
@@ -211,7 +211,7 @@ To migrate, use `runById()` instead, which now returns the same unified `Workflo
 
 ### `toAISdkFormat` function
 
-The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. This change provides clearer naming for stream conversion utilities.
+The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. Use the stream conversion utilities shown below instead.
 
 To migrate, use `toAISdkStream()` instead.
 

package/.docs/guides/migrations/upgrade-to-v1/evals.md

@@ -25,7 +25,7 @@ To migrate, replace all calls to `getScorers()` with `listScorers()`.
 
 ### `runExperiment` to `runEvals`
 
-The `runExperiment()` function has been renamed to `runEvals()`. This change provides clearer naming that better describes the evaluation functionality.
+The `runExperiment()` function has been renamed to `runEvals()` to identify that it runs evaluations.
 
 To migrate, update function calls from `runExperiment` to `runEvals`.
 
@@ -152,7 +152,7 @@ import type {
 
 ### Message content structure to nested format
 
-Tool invocations and text content are now accessed through a nested `content` object structure instead of being flat properties on the message. This change provides better type safety and aligns with the database message format.
+Tool invocations and text content are now accessed through a nested `content` object instead of flat message properties. The nested structure matches the database message format and its types.
 
 To migrate, access tool invocations via `message.content.toolInvocations` and text via `message.content.content` or use the `getTextContentFromMastraDBMessage()` helper.
 

package/.docs/guides/migrations/upgrade-to-v1/memory.md

@@ -260,7 +260,7 @@ To migrate, use `MastraDBMessage` for storage or AI SDK v5 message formats direc
 
 ### `processors` config from Memory constructor
 
-The `processors` config option in the Memory constructor has been deprecated and now throws an error. Processors should be configured at the Agent level instead. This change provides clearer configuration boundaries and better encapsulation.
+The `processors` config option in the Memory constructor is no longer supported and throws an error. Configure processors at the Agent level, where processor behavior is scoped to agent execution.
 
 To migrate, move processor configuration from Memory to Agent using `inputProcessors` and/or `outputProcessors`.
 

package/.docs/guides/migrations/upgrade-to-v1/overview.md

@@ -6,11 +6,11 @@
 
 Mastra v1 was released in January 2026. We recommend starting any new projects with Mastra v1, or upgrading your existing project to continue receiving updates and support.
 
-This guide provides a comprehensive overview of breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.
+This guide covers the breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.
 
 > **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/BTYqqHKUrf) to ask questions.
 
-> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens don't work with Mastra platform — you must create new ones with `mastra auth tokens create`.
+> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens don't work with Mastra platform. Create new ones with `mastra auth tokens create`.
 >
 > If you upgrade to v1 packages without also migrating your `telemetry:` config to `observability:` and creating a Studio project, observability data will stop flowing. Follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) end to end.
 
@@ -18,7 +18,7 @@ This guide provides a comprehensive overview of breaking changes when upgrading
 
 ### Update all Mastra packages to `latest` tag
 
-Use your package manager to update your project's versions. Be sure to update **all** Mastra packages at the same time to ensure compatibility (all `@mastra/*` packages and `mastra`).
+Use your package manager to update your project's versions. Update **all** Mastra packages together to ensure compatibility (all `@mastra/*` packages and `mastra`).
 
 Here's how you update the most commonly used packages:
 

package/.docs/guides/migrations/upgrade-to-v1/processors.md

@@ -27,7 +27,7 @@ import type { InputProcessor } from '@mastra/core/processors';
 
 ### Processor message types from `MastraMessageV2` to `MastraDBMessage`
 
-Processor message types have changed from `MastraMessageV2` to `MastraDBMessage`. This change provides consistency with scorer configuration and better type safety by aligning with the database message format.
+Processor message types have changed from `MastraMessageV2` to `MastraDBMessage`. Processors and scorers now use the database message format and its types.
 
 To migrate, update processor message type imports and usage.
 

package/.docs/guides/migrations/upgrade-to-v1/storage.md

@@ -39,7 +39,7 @@ Run the migration command which automatically deduplicates spans and adds the co
 npx mastra migrate
 ```
 
-The CLI bundles your project, connects to your configured storage, and runs the migration. It keeps the most complete record (based on `endTime` and attributes) when removing duplicates.
+The CLI bundles your project and connects to your configured storage before running the migration. It keeps the most complete record (based on `endTime` and attributes) when removing duplicates.
 
 #### Option 2: Manual SQL (PostgreSQL)
 
@@ -144,7 +144,7 @@ To migrate, update your imports and instantiation:
   });
 ```
 
-> **Note:** If you're using a single store implementation (like `PostgresStore` or `LibSQLStore`) directly, no changes are needed. This only affects code that explicitly uses `MastraStorage` for composite storage.
+> **Note:** If you're using a single store implementation (like `PostgresStore` or `LibSQLStore`) directly, keep the existing configuration. This only affects code that explicitly uses `MastraStorage` for composite storage.
 
 ### Required `id` property for storage instances
 
@@ -168,7 +168,7 @@ const storage = new PostgresStore({
 
 ### Pagination from `offset/limit` to `page/perPage`
 
-All pagination APIs now use `page` and `perPage` instead of `offset` and `limit`. This change provides a more intuitive pagination model that aligns with common web pagination patterns.
+All pagination APIs now use `page` and `perPage` instead of `offset` and `limit`, matching page-based web pagination.
 
 To migrate, update all pagination parameters from `offset/limit` to `page/perPage`. Note that `page` is 0-indexed.
 
@@ -388,9 +388,9 @@ To migrate, use the memory store, remove format parameters, and update code to w
 
 ### Vector store API from positional to named arguments
 
-All vector store methods now use named arguments instead of positional arguments. This change improves code readability and makes method signatures more maintainable.
+All vector store methods now use an arguments object instead of positional arguments. This makes each value's purpose visible at the call site and lets method signatures evolve without relying on argument order.
 
-To migrate, update all vector store method calls to use named arguments.
+To migrate, update all vector store method calls to use an arguments object.
 
 ```diff
 - await vectorDB.createIndex(indexName, 3, 'cosine');
@@ -417,9 +417,9 @@ To migrate, update all vector store method calls to use named arguments.
 
 ### Vector store method renames
 
-The `updateIndexById` and `deleteIndexById` methods have been renamed to `updateVector` and `deleteVector` respectively. This change provides clearer naming that better describes the operations.
+The `updateIndexById` and `deleteIndexById` methods have been renamed to `updateVector` and `deleteVector` respectively. The new names identify that these methods operate on vectors.
 
-To migrate, rename the methods and use named arguments.
+To migrate, rename the methods and pass an arguments object.
 
 ```diff
 - await vectorDB.updateIndexById(indexName, id, update);
@@ -449,9 +449,9 @@ To migrate, pass the connection string as an object property.
 
 ### PGVector `defineIndex` to `buildIndex`
 
-The `defineIndex()` method has been removed in favor of `buildIndex()`. This change provides clearer naming for the index building operation.
+The `defineIndex()` method has been removed in favor of `buildIndex()`, which identifies that the method builds an index.
 
-To migrate, rename the method and use named arguments.
+To migrate, rename the method and pass an arguments object.
 
 ```diff
 - await vectorDB.defineIndex(indexName, 'cosine', { type: 'flat' });
@@ -464,7 +464,7 @@ To migrate, rename the method and use named arguments.
 
 ### `PostgresStore`: `schema` to `schemaName`
 
-The `schema` parameter has been renamed to `schemaName` in the PostgresStore constructor. This change provides clearer naming to avoid confusion with database schema concepts.
+The `schema` parameter has been renamed to `schemaName` in the PostgresStore constructor. The new name identifies the value as the database schema's name.
 
 To migrate, rename the parameter.
 
@@ -521,7 +521,7 @@ To migrate, use paginated methods via domain stores. For fetching all records, u
 
 ### `getTraces` and `getTracesPaginated`
 
-The `getTraces()` and `getTracesPaginated()` methods have been removed from storage. Traces are now handled through the observability package rather than core storage. This change provides better separation of concerns between core storage and observability features.
+The `getTraces()` and `getTracesPaginated()` methods have been removed from storage. Use the observability package to access traces instead of core storage.
 
 To migrate, use observability storage methods instead.
 

package/.docs/guides/migrations/upgrade-to-v1/tools.md

@@ -8,9 +8,9 @@ Tool execution signatures have been updated to use separate input and context pa
 
 ### `createTool` execute signature to `(inputData, context)` format
 
-All `createTool` execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
+All `createTool` execute functions now use a signature with separate `inputData` and `context` parameters instead of a single destructured object. Tool inputs and execution context are now passed independently.
 
-**Note:** This change only applies to `createTool`. If you're using `createStep` for workflows, the signature remains `async (inputData, context)` and doesn't need to be changed.
+This signature change only applies to `createTool`. For workflow `createStep` calls, keep the `async (inputData, context)` signature.
 
 To migrate, update `createTool` signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
 
@@ -88,7 +88,7 @@ To skip the `suspendSchema` or `resumeSchema` validation, don't define `suspendS
 
 ### `RuntimeContext` to `RequestContext`
 
-The `RuntimeContext` class has been renamed to `RequestContext` throughout the tool execution context. This change provides clearer naming that better describes its purpose as request-specific data.
+The `RuntimeContext` class has been renamed to `RequestContext` throughout the tool execution context. The new name identifies the class as request-specific data.
 
 To migrate, update references from `runtimeContext` to `requestContext` in tool execution functions.
 

package/.docs/guides/migrations/upgrade-to-v1/tracing.md

@@ -6,9 +6,9 @@ The observability system has been restructured in v1 with a dedicated `@mastra/o
 
 > **Observability data stops flowing on upgrade:** If you upgrade Mastra packages to v1 without migrating your `telemetry:` config to `observability:`, the old config is ignored at runtime. Your service will start cleanly with no error, but **no traces, logs, or metrics will be sent anywhere**. If you were sending data to Mastra Cloud, the dashboard will go empty.
 >
-> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) — the new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
+> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud). The new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
 
-> **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes still ship from `@mastra/observability` and behave identically, but they're deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`; existing imports of `CloudExporter`/`DefaultExporter` continue to work until they're removed in a future major version.
+> **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes remain available from `@mastra/observability` and behave identically, but they're deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`. Existing imports of `CloudExporter` or `DefaultExporter` continue to work until they're removed in a future major version.
 
 ## Migration paths
 

package/.docs/guides/migrations/upgrade-to-v1/voice.md

@@ -8,7 +8,7 @@ Voice packages have been renamed from speech to voice with updated class names a
 
 ### Voice configuration property names
 
-Voice configuration properties have been renamed for consistency. `speakProvider` is now `output`, `listenProvider` is now `input`, and `realtimeProvider` is now `realtime`. This change provides more intuitive property names.
+Voice configuration properties have been renamed for consistency. `speakProvider` is now `output`, `listenProvider` is now `input`, and `realtimeProvider` is now `realtime`. The new names match each property's role in voice input and output.
 
 To migrate, update configuration property names when configuring agents with voice capabilities.
 

package/.docs/guides/migrations/upgrade-to-v1/workflows.md

@@ -65,7 +65,7 @@ To migrate, rename method calls from `createRunAsync` to `createRun`.
 
 ### `runCount` to `retryCount` (deprecated)
 
-The `runCount` parameter has been deprecated in favor of `retryCount` in workflow step execution. This change provides clearer naming that better describes retry behavior. The old `runCount` still works but shows deprecation warnings.
+The `runCount` parameter has been deprecated in favor of `retryCount` in workflow step execution. The new name identifies the value as the number of retries. The old `runCount` still works but shows deprecation warnings.
 
 To migrate, rename `runCount` to `retryCount` in step execution functions.
 

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

@@ -89,6 +89,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`                                                                                       |
+| [Modal](https://mastra.ai/models/providers/modal)                                              | `modal/*`                  | `MODAL_PROXY_TOKEN`                                                                                   |
 | [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`                                                                                    |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5115 models from 162 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5116 models from 163 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/modal.md

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![Modal logo](https://models.dev/logos/modal.svg)Modal
+
+Access 1 Modal model through Mastra's model router. Authentication is handled automatically using the `MODAL_PROXY_TOKEN` environment variable.
+
+Learn more in the [Modal documentation](https://modal.com/docs/guide/endpoints).
+
+```bash
+MODAL_PROXY_TOKEN=your-api-token
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "modal/thinkingmachines/Inkling-NVFP4"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Modal documentation](https://modal.com/docs/guide/endpoints) for details.
+
+## Models
+
+| Model                                  | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| -------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `modal/thinkingmachines/Inkling-NVFP4` | 1.0M    |       |           |       |       |       | $1         | $5          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://inference.us-west.modal.direct/v1",
+    id: "modal/thinkingmachines/Inkling-NVFP4",
+    apiKey: process.env.MODAL_PROXY_TOKEN,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "modal/thinkingmachines/Inkling-NVFP4"
+      : "modal/thinkingmachines/Inkling-NVFP4";
+  }
+});
+```

package/.docs/models/providers.md

@@ -89,6 +89,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [MiniMax Token Plan (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn-coding-plan)
 - [Mixlayer](https://mastra.ai/models/providers/mixlayer)
 - [Moark](https://mastra.ai/models/providers/moark)
+- [Modal](https://mastra.ai/models/providers/modal)
 - [Model Oracle AI](https://mastra.ai/models/providers/model-oracle-ai)
 - [ModelScope](https://mastra.ai/models/providers/modelscope)
 - [Moonshot AI](https://mastra.ai/models/providers/moonshotai)

package/.docs/reference/acp/acp-agent.md

@@ -2,7 +2,7 @@
 
 # AcpAgent class
 
-The `AcpAgent` class wraps an Agent Client Protocol (ACP)-compatible coding agent as a Mastra subagent. Use it when a parent Mastra agent should delegate repository inspection, code edits, or other ACP-backed tasks to a named subagent.
+The `AcpAgent` class wraps an Agent Client Protocol (ACP)-compatible coding agent as a Mastra subagent. Use it when a parent Mastra agent should delegate repository inspection and code edits. It can also delegate other ACP-backed tasks to the subagent.
 
 If you want the parent agent to call the ACP agent as a tool instead, use [`createACPTool()`](https://mastra.ai/reference/acp/create-acp-tool).
 
@@ -143,7 +143,7 @@ await codeAgent.setModel('claude-sonnet-4-6')
 
 ## Session lifecycle
 
-`AcpAgent` starts the configured `command` on first use, initializes the ACP client, and creates an ACP session. By default, `persistSession` is `true`, so the process and session stay alive across `generate()`, `stream()`, `getAvailableModels()`, and `setModel()` calls.
+`AcpAgent` starts the configured `command` on first use and initializes the ACP client. It then creates an ACP session. By default, `persistSession` is `true`, so the process and session stay alive across `generate()`, `stream()`, `getAvailableModels()`, and `setModel()` calls.
 
 Set `persistSession: false` when each prompt should run in a fresh ACP process:
 
@@ -220,7 +220,7 @@ export const codeAgent = new AcpAgent({
 })
 ```
 
-Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+Use this callback to enforce local policy or inspect the permission title. It can also route the decision to your own approval flow.
 
 ## Related