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

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

@@ -98,7 +98,7 @@ export const claudeCodeAgent = new AcpAgent({
 
 #### `generate(messages, options?)`
 
-Sends the prompt to the ACP agent, buffers text chunks from the ACP response, and returns a Mastra subagent generate result.
+Sends the prompt to the ACP agent and buffers text chunks from the response before returning a Mastra subagent generate result.
 
 ```typescript
 const result = await codeAgent.generate('Inspect the repository and summarize the test setup')

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

@@ -249,7 +249,7 @@ const usage = session.getTokenUsage()
 
 ## Identity
 
-`session.identity` owns the stable identifiers for the conversation: the resource ID, a session `id`, and an `ownerId`. The `id` and `ownerId` are stable for the life of the session and don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage.
+`session.identity` owns the stable identifiers for the conversation: the resource ID and session `id`, plus an `ownerId`. The `id` and `ownerId` are stable for the life of the session and don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage.
 
 ### `session.identity.getId()`
 

package/.docs/reference/agents/channels.md

@@ -309,7 +309,7 @@ The `ResolveResourceIdContext` passed to the function:
 
 ## Thread ID resolution
 
-By default a new channel thread gets a random UUID as its internal Mastra thread id. Pass `resolveThreadId` to pick the id yourself: for example, give the thread the same id as the session it belongs to, matching how your app names threads it creates itself.
+By default a new channel thread gets a random UUID as its internal Mastra thread id. Pass `resolveThreadId` to pick the id yourself: for example, give the thread the same id as its session to match the names your app assigns to threads it creates.
 
 The hook runs after `resolveResourceId`, so the resolved owner is available on the context. Like `resolveResourceId` it runs only when a new thread is created: reused threads keep their stored id and never call the hook. The returned id must be unique across the memory store. If it already belongs to an existing thread, Mastra logs a warning and uses a generated id instead so the existing thread is never overwritten. Return `ctx.defaultThreadId` to keep the built-in behavior.
 

package/.docs/reference/agents/inngest-agent.md

@@ -121,7 +121,7 @@ Returns: [`Promise<InngestAgentStreamResult>`](#inngestagentstreamresult)
 
 #### `resume(runId, resumeData, options?)`
 
-Resumes a suspended Inngest run, for example after a tool approval. Loads the workflow snapshot from storage, finds the suspended step, and sends a resume event to Inngest.
+Resumes a suspended Inngest run, for example after a tool approval. Loads the workflow snapshot from storage and finds the suspended step before sending a resume event to Inngest.
 
 ```typescript
 const { output, cleanup } = await durableAgent.resume(

package/.docs/reference/ai-sdk/overview.md

@@ -2,7 +2,7 @@
 
 # AI SDK
 
-If you're already using the [Vercel AI SDK](https://sdk.vercel.ai) directly and want to add Mastra capabilities like [processors](https://mastra.ai/docs/agents/processors) or [memory](https://mastra.ai/docs/memory/memory-processors) without switching to the full Mastra agent API, [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra) lets you wrap any AI SDK model with these features. This is useful when you want to keep your existing AI SDK code but add input/output processing, conversation persistence, or content filtering.
+If you're already using the [Vercel AI SDK](https://sdk.vercel.ai) directly and want to add Mastra capabilities like [processors](https://mastra.ai/docs/agents/processors) or [memory](https://mastra.ai/docs/memory/memory-processors) without switching to the full Mastra agent API, [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra) lets you wrap any AI SDK model with these features. This is useful when you want to keep your existing AI SDK code but add input/output processing and conversation persistence, including content filtering.
 
 > **Tip:** If you want to use Mastra together with AI SDK UI (e.g. `useChat()`), visit the [AI SDK UI guide](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui).
 

package/.docs/reference/auth/auth0.md

@@ -26,7 +26,7 @@ export const mastra = new Mastra({
 
 **domain** (`string`): Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant. (Default: `process.env.AUTH0_DOMAIN`)
 
-**audience** (`string`): Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API. (Default: `process.env.AUTH0_AUDIENCE`)
+**audience** (`string`): Your Auth0 API identifier/audience, which restricts tokens to your API. (Default: `process.env.AUTH0_AUDIENCE`)
 
 **name** (`string`): Custom name for the auth provider instance. (Default: `"auth0"`)
 

package/.docs/reference/auth/google.md

@@ -4,7 +4,7 @@
 
 ## MastraAuthGoogle class
 
-The `MastraAuthGoogle` class provides authentication for Mastra using Google Workspace. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies, verifies Google ID tokens, and integrates with the Mastra server using the `auth` option.
+The `MastraAuthGoogle` class provides authentication for Mastra using Google Workspace. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies and verifies Google ID tokens. It integrates with the Mastra server through the `auth` option.
 
 ### Usage example
 

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

@@ -46,7 +46,7 @@ then interact with elements using their refs (e.g., @e5).`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
-**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording.
+**recording** (`BrowserRecordingOptions`): Beta option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording.
 
 **excludeTools** (`BrowserToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
 
@@ -54,7 +54,7 @@ then interact with elements using their refs (e.g., @e5).`,
 
 `AgentBrowser` provides 16 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
 
-When `recording` is configured, `AgentBrowser` also adds the alpha `browser_record` and `browser_record_caption` tools. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording).
+When `recording` is configured, `AgentBrowser` also adds the Beta `browser_record` and `browser_record_caption` tools. See [Browser recording (Beta)](https://mastra.ai/docs/browser/overview).
 
 ### Core tools
 

package/.docs/reference/browser/browser-viewer.md

@@ -2,7 +2,7 @@
 
 # BrowserViewer
 
-The `BrowserViewer` class provides browser automation for CLI-based tools. It launches Chrome via Playwright, exposes a Chrome DevTools Protocol (CDP) URL, and automatically injects it into CLI commands run through workspace tools.
+The `BrowserViewer` class provides browser automation for CLI-based tools. It launches Chrome through Playwright and exposes a Chrome DevTools Protocol (CDP) URL. It automatically injects that URL into CLI commands run through workspace tools.
 
 Use `BrowserViewer` when your agent drives a browser through a CLI tool like `browser-use`, `agent-browser`, or `browse`. For SDK-based browser automation, use [`AgentBrowser`](https://mastra.ai/reference/browser/agent-browser) or [`StagehandBrowser`](https://mastra.ai/reference/browser/stagehand-browser).
 

package/.docs/reference/browser/stagehand-browser.md

@@ -63,7 +63,7 @@ Use stagehand_extract to get data from pages.`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
-**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording.
+**recording** (`BrowserRecordingOptions`): Beta option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording.
 
 **excludeTools** (`StagehandToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
 
@@ -71,7 +71,7 @@ Use stagehand_extract to get data from pages.`,
 
 `StagehandBrowser` provides 7 AI-powered tools for browser automation.
 
-When `recording` is configured, `StagehandBrowser` also adds the alpha `browser_record` and `browser_record_caption` tools. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording).
+When `recording` is configured, `StagehandBrowser` also adds the Beta `browser_record` and `browser_record_caption` tools. See [Browser recording (Beta)](https://mastra.ai/docs/browser/overview).
 
 Core tools:
 

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/index.md

@@ -243,7 +243,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering)
 - [Spans](https://mastra.ai/reference/observability/tracing/spans)
 - [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor)
-- [CostGuardProcessor](https://mastra.ai/reference/processors/cost-guard-processor)
 - [LanguageDetector](https://mastra.ai/reference/processors/language-detector)
 - [MessageHistory](https://mastra.ai/reference/processors/message-history-processor)
 - [ModerationProcessor](https://mastra.ai/reference/processors/moderation-processor)
@@ -258,6 +257,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
 - [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
 - [SystemPromptScrubber](https://mastra.ai/reference/processors/system-prompt-scrubber)
+- [TokenCostControl](https://mastra.ai/reference/processors/token-cost-control)
 - [TokenLimiterProcessor](https://mastra.ai/reference/processors/token-limiter-processor)
 - [ToolCallFilter](https://mastra.ai/reference/processors/tool-call-filter)
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)

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.