@mastra/mcp-docs-server 1.2.16-alpha.3 → 1.2.16-alpha.4

package/.docs/reference/channels/channel-provider.md

@@ -2,7 +2,7 @@
 
 # ChannelProvider
 
-`ChannelProvider` is the interface that platform integrations implement to connect agents to a messaging platform. A provider owns the full lifecycle of an integration: app provisioning and OAuth, webhook routing and event handling, adapter creation and agent wiring, and credential management.
+`ChannelProvider` is the interface that platform integrations implement to connect agents to a messaging platform. A provider owns the full integration lifecycle. This includes app provisioning with OAuth, webhook routing with event handling, adapter creation and agent wiring, and credential management.
 
 Register providers on the `Mastra` constructor under `channels`, keyed by an id you choose. Each provider's routes are merged into the server's API routes automatically, and `initialize()` runs during Mastra startup.
 

package/.docs/reference/channels/slack-provider.md

@@ -2,7 +2,7 @@
 
 # SlackProvider
 
-`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps via the Manifest API, runs the OAuth install flow, rotates configuration tokens, and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/integrations/channels/slack) on the agent's `channels.adapters` instead.
+`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps through the Manifest API and runs the OAuth install flow. It also rotates configuration tokens and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/integrations/channels/slack) on the agent's `channels.adapters` instead.
 
 ## Usage example
 

package/.docs/reference/cli/mastra.md

@@ -226,7 +226,7 @@ The content digest excludes `experiment-worker-manifest.json` to avoid a self-re
 
 The worker implements the pinned experiment companion-worker protocol version `1`. It reads strict UTF-8 NDJSON frames from standard input and requires every frame, including the last one, to end with a newline. Frames larger than 1 MiB, malformed or truncated frames, unsupported protocol or canonicalization versions, and messages that don't match the active experiment correlation are rejected as protocol failures.
 
-A run request must match the artifact's embedded build ID and include the ordered dataset item count and SHA-256 attestation. The worker emits contiguous sequence numbers starting at `0`, timer-driven heartbeats, awaited experiment lifecycle events, and exactly one terminal event. Cancellation must match the active protocol version, experiment ID, job ID, attempt, and idempotency key.
+A run request must match the artifact's embedded build ID and include the ordered dataset item count and SHA-256 attestation. The worker emits contiguous sequence numbers starting at `0`, timer-driven heartbeats, awaited experiment lifecycle events, and exactly one terminal event. Cancellation must match the active protocol version and experiment ID, plus the job ID, attempt, and idempotency key.
 
 Protocol exit codes are:
 
@@ -528,7 +528,7 @@ Emit machine-readable JSON.
 
 Provisions and attaches a managed database, then polls until it's ready. Provisioning errors are printed with the provider's error detail.
 
-By default the database is scoped to a single environment: pass an environment argument to pick it, or omit the argument to have the CLI pick for you. When the project has one environment, that environment is used. When it has several, the CLI prompts you to select one interactively; in non-interactive contexts (CI, `--json`) an environment argument is required. Pass `--shared` to attach a project-scoped database that's shared by every environment instead.
+By default, the database is scoped to a single environment. Pass an environment argument to select it. If you omit the argument, the CLI uses the project's only environment or prompts you when several are available. In non-interactive contexts (CI, `--json`) an environment argument is required. Pass `--shared` to attach a project-scoped database that's shared by every environment instead.
 
 Environment-scoped databases inherit their provider region from the environment. Shared databases accept `--region`.
 
@@ -797,7 +797,7 @@ Lists all environment variables for the linked project. Values are partially mas
 
 ### `mastra server env set`
 
-Sets an environment variable. The CLI reads the current map, applies the change, and uploads the result.
+Sets an environment variable. The CLI reads the current map and applies the change before uploading the result.
 
 ```bash
 mastra server env set <key> <value>
@@ -1226,7 +1226,7 @@ mastra api agent get <agentId>
 
 #### `mastra api agent run`
 
-Runs an agent with JSON input. Use command help to see examples for text prompts, chat messages, and memory thread options.
+Runs an agent with JSON input. Use command help to see examples for text prompts and chat messages, including memory thread options.
 
 ```bash
 mastra api agent run <agentId> <input>
@@ -1370,7 +1370,7 @@ mastra api thread get <threadId>
 
 #### `mastra api thread create`
 
-Creates a memory thread. Pass one JSON input object; the CLI splits fields such as `agentId` into query parameters when required by the server route.
+Creates a memory thread. Pass one JSON input object. The CLI splits fields such as `agentId` into query parameters when required by the server route.
 
 ```bash
 mastra api thread create <input>

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -4,7 +4,7 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller (the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management) and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller (the coding agent behind [Mastra Code](https://code.mastra.ai), with its modes, tools, memory, and thread management) and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 To construct the `Mastra` instance yourself (for example in a deployable entry file), use `prepareAgentControllerMount()` from the same package, which returns the constructor args plus a `finalize()` callback.
 

package/.docs/reference/coding-agent/build-base-prompt.md

@@ -74,4 +74,5 @@ const prompt = buildBasePrompt({
 
 ## Related
 
-- [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent)
+- [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent)
+- [Mastra Code](https://code.mastra.ai)

package/.docs/reference/configuration.md

@@ -801,7 +801,7 @@ export const mastra = new Mastra({
 
 **Type:** `(err: Error, c: Context) => Response | Promise<Response>`
 
-Custom error handler called when an unhandled error occurs. Use this to customize error responses, log errors to external services like Sentry, or implement custom error formatting.
+Custom error handler called when an unhandled error occurs. Use this to customize error responses or log errors to external services such as Sentry. You can also implement custom error formatting.
 
 This hook is supported by all server adapters. The `c` parameter provides a Hono-compatible context object: for non-Hono adapters (Koa, Express, Fastify), a shim is provided with commonly used methods like `c.json()` and `c.req.path`.
 
@@ -830,7 +830,7 @@ export const mastra = new Mastra({
 
 **Type:** `(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined`
 
-Custom handler called when a request fails Zod schema validation. Use this to customize validation error responses, change the status code, or format errors to match your API standards.
+Custom handler called when a request fails Zod schema validation. Use this to customize validation error responses and change the status code, or to format errors to match your API standards.
 
 Return a `{ status, body }` object to override the default `400` response, or `undefined` to use the default behavior. This hook is supported by all server adapters (Hono, Express, Fastify, Koa).
 
@@ -886,7 +886,7 @@ export const mastra = new Mastra({
 
 Base path for hosting [Studio](https://mastra.ai/docs/studio/overview). Use this to host the Studio on a sub-path of your existing application instead of the root.
 
-This is useful when integrating with existing applications, using authentication tools like Cloudflare Zero Trust that benefit from shared domains, or managing multiple services under a single domain.
+This is useful when integrating with existing applications or authentication tools such as Cloudflare Zero Trust that benefit from shared domains. It also supports managing multiple services under one domain.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/core/getAgentById.md

@@ -8,7 +8,7 @@ Use `mastra.getAgentById(id)` to retrieve the code-defined agent. Use `await mas
 
 ## Usage example
 
-The following example registers an agent, retrieves it by ID, and uses the returned agent.
+The following example registers an agent and retrieves it by ID before using the returned agent.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'

package/.docs/reference/core/getWorkflow.md

@@ -2,7 +2,7 @@
 
 # Mastra.getWorkflow()
 
-The `.getWorkflow()` method is used to retrieve a workflow by its registration key. This method provides full TypeScript type inference for workflow input and output schemas.
+The `.getWorkflow()` method is used to retrieve a workflow by its registration key. The method provides full TypeScript type inference for workflow input and output schemas.
 
 ## Usage example
 
@@ -19,7 +19,7 @@ await run.startAsync({
 
 ## Type inference
 
-For best TypeScript support, use `getWorkflow()` with the workflow's **registration key** (the key used when adding the workflow to Mastra). This provides full type inference for:
+For best TypeScript support, use `getWorkflow()` with the workflow's **registration key** (the key used when adding the workflow to Mastra). The registration key provides full type inference for:
 
 - Input data schemas
 - Output data schemas

package/.docs/reference/core/mastra-class.md

@@ -4,7 +4,7 @@
 
 The `Mastra` class is the central orchestrator in any Mastra application, managing agents, workflows, storage, logging, observability, and more. Typically, you create a single instance of `Mastra` to coordinate your application.
 
-Think of `Mastra` as a top-level registry where you register agents, workflows, tools, and other components that need to be accessible throughout your application.
+`Mastra` is the top-level registry where you register agents, workflows, tools, and other components that need to be accessible throughout your application.
 
 ## Usage example
 

package/.docs/reference/deployer/netlify.md

@@ -50,7 +50,7 @@ export const mastra = new Mastra({
 - `target?: 'serverless' | 'edge'`: Deploy target for Netlify. Defaults to `'serverless'`.
 
   - `'serverless'`: Standard [Netlify Functions](https://docs.netlify.com/functions/overview/) (Node.js runtime, 60s default timeout).
-  - `'edge'`: [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/) (Deno-based runtime, runs at the edge closest to users, without a fixed timeout).
+  - `'edge'`: [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/) (Deno-based runtime that runs at the edge closest to users without a fixed timeout).
 
 ### Edge functions example
 

package/.docs/reference/deployer.md

@@ -2,7 +2,7 @@
 
 # Deployer
 
-The Deployer handles the deployment of standalone Mastra applications by packaging code, managing environment files, and serving applications using the Hono framework. Concrete implementations must define the deploy method for specific deployment targets.
+The Deployer handles the deployment of standalone Mastra applications by packaging code and managing environment files while serving applications through the Hono framework. Concrete implementations must define the deploy method for specific deployment targets.
 
 ## Usage example
 

package/.docs/reference/editor/prompt-blocks.md

@@ -2,7 +2,7 @@
 
 # Prompt blocks
 
-Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text, embedded prompt blocks, and references to independently versioned prompt blocks.
+Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text with embedded prompt blocks and references to independently versioned prompt blocks.
 
 See [Prompt blocks](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
 

package/.docs/reference/editor/tools.md

@@ -2,7 +2,7 @@
 
 # Tool configuration
 
-Editor stores tool selections as part of an agent version. A stored configuration can add registered tools, tools from integration providers, and tools from Model Context Protocol (MCP) clients.
+Editor stores tool selections as part of an agent version. A stored configuration can add registered tools and tools from integration providers, as well as tools from Model Context Protocol (MCP) clients.
 
 See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
 

package/.docs/reference/evals/completeness.md

@@ -67,7 +67,7 @@ The scorer evaluates completeness through linguistic element coverage analysis.
 
 1. Extracts key elements:
 
-   - Nouns and named entities
+   - Nouns and entities such as names
    - Action verbs
    - Topic-specific terms
    - Normalized word forms

package/.docs/reference/evals/noise-sensitivity.md

@@ -177,7 +177,7 @@ Include in your test harness to:
 
 - Benchmark different models' noise resistance before deployment
 - Identify agents vulnerable to manipulation during development
-- Create detailed test coverage for various noise types
+- Create detailed test coverage for multiple noise types
 - Ensure consistent behavior across updates
 
 ### Security Testing

package/.docs/reference/evals/summarization.md

@@ -2,7 +2,7 @@
 
 # Summarization scorer
 
-The `createSummarizationScorer()` function creates a scorer that evaluates a summary on two axes: whether every claim it makes is supported by the source text, and whether it preserves the information the source states. The final score is the lower of the two, so a summary can't pass by being faithful but empty, or thorough but wrong.
+The `createSummarizationScorer()` function creates a scorer that evaluates a summary on two axes: whether every claim has source-text support and whether the summary preserves the source information. The final score is the lower of the two. A summary can't pass by being faithful but empty or by being thorough but wrong.
 
 The summary is the agent's last message that carries text, and the source text defaults to the first user message of the run input. Pass `source` or `sourceExtractor` when the text being summarized lives somewhere else, such as a tool result.
 

package/.docs/reference/file-based-agents/config.md

@@ -101,7 +101,7 @@ Missing `instructions.md`, `instructions.ts`, and `config.instructions` fails th
 
 ## Discovery lifecycle
 
-File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/`, imports TypeScript and JavaScript modules, reads markdown instructions and skills, copies workspace seed files, and registers the assembled primitives with your Mastra app.
+File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/` and imports TypeScript and JavaScript modules. It also reads markdown instructions and skills. The bundler then copies workspace seed files and registers the assembled primitives with your Mastra app.
 
 After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent.
 

package/.docs/reference/file-based-agents/skills.md

@@ -22,11 +22,11 @@ Always report temperatures in Celsius and Fahrenheit. Include the user's preferr
 
 ## Skills vs tools vs instructions
 
-| Need                                                 | Use                                                                             | Why                                                                  |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Always-on identity, tone, or rules                   | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The model should see the guidance every turn.                        |
-| Callable action with inputs and outputs              | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | The model needs to execute code, call APIs, or perform side effects. |
-| Detailed reference or procedure loaded when relevant | `skills/`                                                                       | The model only needs the full guidance for specific tasks.           |
+| Need                                                 | Use                                                                             | Why                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Always-on identity, tone, or rules                   | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The model should see the guidance every turn.                                                 |
+| Callable action with inputs and outputs              | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | The model needs to execute code or call APIs, including operations that perform side effects. |
+| Detailed reference or procedure loaded when relevant | `skills/`                                                                       | The model only needs the full guidance for specific tasks.                                    |
 
 ## Skill formats
 

package/.docs/reference/file-based-agents/workspace.md

@@ -15,7 +15,7 @@ Without `workspace.ts`, a file-based agent gets a default [`Workspace`](https://
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) rooted at the agent's bundled workspace directory.
 - [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) with the same working directory.
 
-This gives the agent file tools and shell tools automatically. The default workspace is per agent; subagents get nested workspace directories under their parent agent's workspace path.
+This gives the agent file tools and shell tools automatically. The default workspace is per agent. Subagents get nested workspace directories under their parent agent's workspace path.
 
 ## Quickstart
 

package/.docs/reference/logging/pino-logger.md

@@ -149,7 +149,7 @@ You can create custom transports using the `createCustomTransport` utility to in
 
 ### Sentry transport example
 
-Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.
+Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. The custom transport forwards logs to an external system such as Sentry for advanced monitoring and observability.
 
 ```typescript
 import { createCustomTransport } from '@mastra/core/loggers'

package/.docs/reference/memory/observational-memory.md

@@ -87,7 +87,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.
 
-**observation.blockAfter** (`number`): Safety net that forces a synchronous (blocking) observation when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 forces a blocking observation at 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Between messageTokens and blockAfter, only async buffering and activation run; buffered activation still preserves a minimum remaining context (the smaller of 1000 tokens or the retention floor). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
+**observation.blockAfter** (`number`): Safety net for when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 resolves to 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Above this point, activation uses the smallest set of buffered chunks that reaches the retention target, even when that overshoots the target by more than the usual safeguard allows. It never activates more chunks than are needed to reach the retention target, so it removes only slightly more history than a normal activation. It changes the result only when the retention floor is above roughly 20,000 tokens; with the default bufferActivation (a 6k floor) it has no observable effect. Activation usually keeps a minimum remaining context (the smaller of 1000 tokens or the retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less. Crossing blockAfter does not trigger a blocking observation. A synchronous (blocking) observation runs when the messageTokens threshold is reached and buffered activation did not happen. Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to 0 to omit previous observations entirely, or false to disable truncation explicitly.
 
@@ -353,7 +353,7 @@ export const agent = new Agent({
 
 Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
 
-The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. Above the `blockAfter` threshold, activation may overshoot the retention target instead of activating fewer chunks. If the threshold is reached and no buffered chunk activates, a synchronous observation runs instead.
 
 Default settings:
 
@@ -383,7 +383,7 @@ export const agent = new Agent({
           bufferTokens: 5_000,
           // Activate to retain 30% of threshold
           bufferActivation: 0.7,
-          // Force synchronous observation at 1.5x threshold
+          // Above 1.5x the threshold, let activation overshoot the retention target
           blockAfter: 1.5,
         },
         reflection: {
@@ -787,6 +787,8 @@ Mastra also injects scope-aware usage instructions into the agent's context. For
 
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \[p1] — call again with partIndex: 1 to see the full content without loading every part.
 
+**charOffset** (`number`): Character position to continue reading a truncated single part. Only applies with cursor and partIndex. When a part is larger than the token budget, the result includes nextCharOffset — pass that exact value here in the next call to read the following chunk. The chunks concatenate to the original part text. (Default: `0`)
+
 **before** (`string`): For mode: "threads" only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. "2026-03-15", "2026-03-10T00:00:00Z").
 
 **after** (`string`): For mode: "threads" only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. "2026-03-01", "2026-03-10T00:00:00Z").
@@ -809,10 +811,16 @@ Mastra also injects scope-aware usage instructions into the agent's context. For
 
 **hasPrevPage** (`boolean`): Whether more messages exist before this page.
 
-**truncated** (`boolean`): Present and true when the output was capped by the token budget. The agent can paginate or use partIndex to access remaining content.
+**truncated** (`boolean`): Present and true when the output was capped by the token budget. The agent can paginate or use partIndex to access remaining content. When a single part is itself too large, the partIndex result includes nextCharOffset for continuing within the part.
 
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when truncated is true.
 
+**charOffset** (`number`): On single-part results (partIndex), the character position this chunk starts at. 0 unless the call passed a charOffset.
+
+**nextCharOffset** (`number`): On single-part results, present when the part was truncated and more content remains. Pass this value as charOffset in the next call to continue reading from where this chunk ended.
+
+**note** (`string`): On truncated single-part results, the exact follow-up call for retrieving the next chunk.
+
 ### Returns (threads mode)
 
 **threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with ← current.

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

@@ -2,7 +2,7 @@
 
 # Agent class
 
-The Agent class has been updated with reorganized voice methods, updated property access patterns, and streamlined streaming APIs.
+The Agent class has been updated with reorganized voice methods and property access patterns, plus streamlined streaming APIs.
 
 ## Changed
 
@@ -70,7 +70,7 @@ To migrate, update all imports and parameter names from `RuntimeContext`/`runtim
 
 ### Direct property access to getter methods
 
-Direct property access to `agent.llm`, `agent.tools`, and `agent.instructions` is deprecated. This change provides better encapsulation and consistency with the broader API design.
+Direct property access to `agent.llm`, `agent.tools`, and `agent.instructions` is deprecated. The accessors improve encapsulation and align with the broader API design.
 
 To migrate, replace property access with the corresponding getter methods.
 
@@ -146,7 +146,7 @@ To migrate, update processor method names.
 
 Mastra v1 continues to accept both Zod v3 and Zod v4 schemas in public agent APIs that take structured output schemas. This includes methods such as `agent.generateLegacy()` and `agent.streamLegacy()` and the related option types.
 
-If you already pass Zod schemas to agent APIs, no migration is required for Zod version compatibility. Keep your existing schema imports:
+Existing Zod schemas passed to agent APIs don't require migration for Zod version compatibility. Keep your existing schema imports:
 
 ```ts
 import { z as z3 } from 'zod/v3'

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

@@ -148,7 +148,7 @@ client.memory.listMessages({
 
 ### `getMemoryThread` parameter structure
 
-The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
+The `getMemoryThread` method parameter structure has been updated. The new structure aligns the API across memory methods.
 
 To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
 

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

@@ -74,7 +74,7 @@ const scorer = createScorer({
 
 ### Scorer configuration from `name` to `id`
 
-Scorers now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities.
+Scorers now require an `id` field instead of `name`. The `name` field is now optional. The new field aligns scorers with other Mastra entities.
 
 To migrate, update scorer definitions to use `id` as the required field.
 

package/.docs/reference/migrations/upgrade-to-v1/mastra.md

@@ -49,7 +49,7 @@ const mastra = new Mastra({
 
 ### Required `id` parameter for all mastra primitives
 
-All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.
+All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. Required IDs standardize the Mastra API and prevent ID conflicts.
 
 All these primitives also now have `get`, `list`, and `add` functions.
 

package/.docs/reference/migrations/upgrade-to-v1/mcp.md

@@ -59,7 +59,7 @@ To migrate, replace all calls to `mcp.getToolsets()` with `mcp.listToolsets()`.
 
 ### MCP tool context properties organization
 
-Context properties in MCP tools are now organized under the `context.mcp` namespace. This change provides better organization and clearer API surface for MCP-specific functionality.
+Context properties in MCP tools are now organized under the `context.mcp` namespace. The namespace organizes MCP-specific functionality under a clear API surface.
 
 To migrate, access MCP-specific properties like `elicitation` and `extra` through `context.mcp` instead of directly from the context parameter.
 

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

@@ -108,7 +108,7 @@ Work through this checklist in order, starting with high-impact changes that aff
 - Update storage methods from `get*` to `list*` pattern - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
 - Replace direct property access with getter methods - [Mastra Class](https://mastra.ai/reference/migrations/upgrade-to-v1/mastra), [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
 - Update memory scope if relying on default `thread` scope - [Memory](https://mastra.ai/reference/migrations/upgrade-to-v1/memory)
-- Update vector store calls to use named arguments - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
+- Update vector store calls to use arguments by name - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
 - Remove `format` parameter from agent methods - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
 - Update voice methods to use `agent.voice` namespace - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
 - Rename configuration property `processors` to `spanOutputProcessors` (if using custom processors) - [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)

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

@@ -8,7 +8,7 @@ Processor interfaces have been updated to use consistent naming patterns and dat
 
 ### Processor configuration from `name` to `id`
 
-Processors now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities like scorers and agents.
+Processors now require an `id` field instead of `name`. The `name` field is now optional. The new field aligns processors with other Mastra entities such as scorers and agents.
 
 To migrate, update processor definitions to use `id` as the required field.
 

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

@@ -93,7 +93,7 @@ USING snapshot::jsonb;
 
 ### Storage composition in `MastraCompositeStore`
 
-`MastraCompositeStore` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
+`MastraCompositeStore` can now compose storage domains from different adapters. Use it when different purposes require different databases, such as PostgreSQL for memory and workflows with a specialized database for observability.
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'
@@ -386,7 +386,7 @@ To migrate, use the memory store, remove format parameters, and update code to w
 + const saved = saveResult?.messages; // MastraDBMessage[]
 ```
 
-### Vector store API from positional to named arguments
+### Vector store API from positional arguments to arguments by name
 
 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.
 
@@ -430,7 +430,7 @@ To migrate, rename the methods and pass an arguments object.
 
 ### PGVector constructor from connection string to object
 
-The PGVector constructor now requires object parameters instead of a connection string. This change provides a more consistent API across all storage adapters.
+The PGVector constructor now requires object parameters instead of a connection string. Object parameters align the API across storage adapters.
 
 To migrate, pass the connection string as an object property.
 
@@ -484,7 +484,7 @@ const pgStore = new PostgresStore({
 
 ### Score storage methods to `listScoresBy*` pattern
 
-Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change provides consistency with the broader API naming conventions.
+Score storage APIs have been renamed to follow the `listScoresBy*` pattern. The new names follow the broader API naming conventions.
 
 To migrate, update method names from `getScores` to `listScoresByScorerId` and related variants.
 
@@ -500,7 +500,7 @@ To migrate, update method names from `getScores` to `listScoresByScorerId` and r
 
 ### Non-paginated storage functions
 
-Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. This change provides consistency across the API and prevents accidental loading of large datasets.
+Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. Pagination aligns list operations across the API and prevents accidental loading of large datasets.
 
 To migrate, use paginated methods via domain stores. For fetching all records, use `perPage: false`.
 

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

@@ -32,7 +32,7 @@ createTool({
 
 ### `createTool` context properties organization
 
-Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
+Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. The namespaces organize these properties under a clearer API surface.
 
 For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
 

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -78,7 +78,7 @@ Force-flushes any buffered LLM Observability data to Datadog without shutting do
 async shutdown(): Promise<void>
 ```
 
-Force-finishes any APM spans that weren't properly closed, flushes pending LLM Observability data, disables the LLM Observability integration, and clears all internal state.
+Force-finishes any APM spans that weren't properly closed and flushes pending LLM Observability data. It then disables the integration and clears all internal state.
 
 ## Usage examples
 

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -146,7 +146,7 @@ Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute:
 }
 ```
 
-This format ensures compatibility with all OTEL-compatible backends and collectors.
+The format is compatible with all OTEL-compatible backends and collectors.
 
 ## Related
 

package/.docs/reference/observability/tracing/exporters/arize.md

@@ -2,7 +2,7 @@
 
 # ArizeExporter
 
-Sends Tracing data to Arize Phoenix, Arize AX, or any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
+Sends Tracing data to Arize Phoenix or Arize AX, as well as any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
 
-> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
+> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior. `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
@@ -183,7 +183,7 @@ The exporter batches tracing spans, logs, metrics, scores, and feedback for effi
 ### Signal Processing
 
 - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
-- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for that signal type
 - All supported signal batches are uploaded to their matching Cloud publish endpoints during `flush()` and `shutdown()`
 
 ## `MastraCloudSpanRecord`

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -199,7 +199,7 @@ The probe timer doesn't keep the Node.js process alive, so short-lived and serve
 ### Signal Processing
 
 - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
-- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for that signal type
 - All supported signal batches are uploaded to their matching publish endpoints during `flush()` and `shutdown()`
 
 ## Span wire format

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -2,7 +2,7 @@
 
 # OtelExporter
 
-Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions; logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
+Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions. Logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/sentry.md

@@ -51,7 +51,7 @@ Force flushes any pending spans to Sentry without shutting down the exporter. Wa
 async shutdown(): Promise<void>
 ```
 
-Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.
+Ends all active spans and clears internal state before closing the Sentry connection. Waits up to 2 seconds for pending data to be sent.
 
 ## Usage