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

package/.docs/docs/agents/acp.md

@@ -11,7 +11,7 @@ ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other ex
 - A Mastra agent should delegate code inspection, editing, or repository tasks to an external coding agent.
 - An ACP-compatible agent process should stay alive across calls so it can keep session context.
 - A parent agent needs real-time output from a coding agent while the task runs.
-- An ACP-compatible agent needs permission prompts before it reads files, writes files, or runs actions.
+- An ACP-compatible agent needs permission prompts before it reads files or writes files, or alternatively runs actions.
 - File access should go through Mastra's workspace abstraction instead of direct process-only file access.
 
 ## How ACP works
@@ -25,8 +25,8 @@ The flow is:
 3. The client sends ACP `initialize` and `session/new` requests.
 4. Mastra sends the user task to the ACP agent with `session/prompt`.
 5. The ACP agent streams session updates and message chunks back to Mastra.
-6. Mastra returns the buffered output, emits streaming chunks, or handles permission input.
-7. The ACP connection stops the process after the prompt when `persistSession` is `false`; `AcpAgent` can keep a reusable process alive across calls by default.
+6. Mastra returns the buffered output or emits streaming chunks, or alternatively handles permission input.
+7. The ACP connection stops the process after the prompt when `persistSession` is `false`. `AcpAgent` can keep a reusable process alive across calls by default.
 
 During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
 
@@ -84,7 +84,7 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Delegate code editing tasks to the code-agent subagent.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: {
     codeAgent,
   },
@@ -113,7 +113,7 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: {
     codeAgentTool,
   },

package/.docs/docs/agents/agent-approval.md

@@ -6,7 +6,7 @@ Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/wor
 
 ## When to use agent approval
 
-- **Destructive or irreversible actions** such as deleting records, sending emails, or processing payments.
+- **Destructive or irreversible actions** such as deleting records or sending emails, or alternatively processing payments.
 - **Cost-heavy operations** like calling expensive third-party APIs where you want to verify arguments first.
 - **Conditional confirmation** where a tool starts executing and then discovers it needs the user to confirm or supply extra data before finishing.
 
@@ -60,7 +60,7 @@ Mastra offers two distinct mechanisms for pausing tool calls: **pre-execution ap
 
 Pre-execution approval pauses a tool call _before_ its `execute` function runs. The LLM still decides which tool to call and provides arguments, but `execute` doesn't run until you explicitly approve.
 
-Two flags control this, combined with OR logic. If _either_ is `true`, the call pauses:
+The flags control this, combined with OR logic. If _either_ is `true`, the call pauses:
 
 | Flag                        | Where to set it                   | Scope                                       |
 | --------------------------- | --------------------------------- | ------------------------------------------- |
@@ -92,7 +92,7 @@ for await (const chunk of stream.fullStream) {
 
 #### Conditional approval with a function
 
-Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval dynamically — for example, only for tools whose name matches a pattern:
+Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:
 
 ```typescript
 const stream = await agent.stream('Clean up old records', {
@@ -100,7 +100,7 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above doesn't override it. If the function throws, the call requires approval (fail-safe).
+A tool's own `requireApproval` setting takes precedence over the function above. Its rule decides whether that tool needs approval. If the function throws, the call requires approval as a fail-safe.
 
 > **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
 
@@ -133,7 +133,7 @@ const weatherTool = createTool({
 })
 ```
 
-> **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
+> **Note:** `suspend()` doesn't throw, return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`
 
@@ -172,11 +172,11 @@ if (output.finishReason === 'suspended') {
 | Decline method     | `declineToolCall({ runId })` | `declineToolCallGenerate({ runId, toolCallId })` |
 | Result             | Stream to iterate            | Full output object                               |
 
-> **Note:** `toolCallId` is optional on all four methods. Pass it when multiple tool calls may be pending at the same time (common in supervisor agents). When omitted, the agent resumes the most recent suspended tool call.
+> **Note:** `toolCallId` is optional on all four methods. Pass it when multiple tool calls may be pending (common in supervisor agents). When omitted, the agent resumes the most recent suspended tool call.
 
 ## Tool-level approval
 
-Instead of pausing every tool call at the agent level, you can mark individual tools as requiring approval. This gives you granular control: only specific tools pause, while others execute immediately.
+Instead of pausing every tool call at the agent level, you can mark individual tools as requiring approval. You get fine-grained control: only specific tools pause, while others execute immediately.
 
 ### Approval using `requireApproval`
 
@@ -303,7 +303,9 @@ const agent = new Agent({
 })
 ```
 
-When enabled, the agent detects suspended tools from message history on the next user message, extracts `resumeData` based on the tool's `resumeSchema`, and automatically resumes the tool. The following example shows a complete conversational flow:
+When enabled, the agent detects suspended tools from message history on the next user message. It extracts `resumeData` based on the tool's `resumeSchema`, then automatically resumes the tool.
+
+The following example shows a complete conversational flow:
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -386,7 +388,7 @@ Both approaches work with the same tool definitions. Automatic resumption trigge
 
 ## Resuming after a restart
 
-The examples above hold on to `stream.runId` between suspension and approval. That works while the process stays alive, but in production the approval often arrives later — after a page refresh, a server restart, or on a different server instance behind a load balancer.
+The examples above hold on to `stream.runId` between suspension and approval. That works while the process stays alive, but in production the approval often arrives later, after a page refresh, a server restart, or on a different server instance behind a load balancer.
 
 Use [`listSuspendedRuns()`](https://mastra.ai/reference/agents/listSuspendedRuns) to rediscover the pending run for a conversation from storage:
 
@@ -414,7 +416,7 @@ if (run && toolCall) {
 }
 ```
 
-Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `args`, and `requiresApproval`). Approval suspensions (`requiresApproval: true`) are answered with `approveToolCall()` / `declineToolCall()`, while `suspend()`-based suspensions carry their `suspendPayload` and expect `resumeStream()` with resume data — so you can rebuild the right UI for either flow without keeping any state in memory.
+Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `args`, and `requiresApproval`). Approval suspensions (`requiresApproval: true`) are answered with `approveToolCall()` / `declineToolCall()`, while `suspend()`-based suspensions carry their `suspendPayload` and expect `resumeStream()` with resume data, so you can rebuild the right UI for either flow without keeping any state in memory.
 
 `sendToolApproval()` uses the same storage-backed discovery automatically: when no active run is found in memory for the thread, it looks up the suspended run in storage before failing. If several suspended runs match the thread, pass a `toolCallId` to disambiguate.
 
@@ -477,7 +479,7 @@ const supervisorAgent = new Agent({
   name: 'Supervisor Agent',
   instructions: `You coordinate data retrieval tasks.
     Delegate to data-agent for user lookups.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: { dataAgent },
   memory: new Memory(),
 })

package/.docs/docs/agents/code-mode.md

@@ -6,7 +6,9 @@
 
 > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response. Instead of calling tools one turn at a time, the model writes a tailored function for the user query that orchestrates your existing tools as `external_*` functions, reduces or aggregates their results, and returns one structured answer.
+Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response.
+
+Instead of calling tools one turn at a time, the model writes a tailored function for the user query. The function orchestrates your existing tools as `external_*` functions and reduces or aggregates their results into one structured answer.
 
 [`createCodeMode()`](https://mastra.ai/reference/tools/create-code-mode) returns this tool with the default `id` of `execute_typescript`. The `id` is configurable, so an agent can have several code mode tools at once, each scoped to a different set of tools (see [Scoping tools across multiple code tools](#scoping-tools-across-multiple-code-tools)).
 
@@ -21,15 +23,19 @@ Use code mode when an agent touches multiple tools to answer a user query or per
 
 ## How it works
 
-Without code mode, multi-tool queries can run the agentic loop several times: the model chooses a tool, reads the result, chooses again, and repeats. Each turn adds the full tool response to the agent's context window which can lead to poorer reasoning and increased token usage.
+Without code mode, multi-tool queries can run the agentic loop several times. The model chooses a tool and reads the result. It repeats the process as needed.
+
+Each turn adds the full tool response to the agent's context window which can lead to poorer reasoning and increased token usage.
 
 With code mode, your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, and the function can reduce or aggregate results before returning one response to the agent.
 
 The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
 
+Transports that bring their own execution boundary are the exception: with [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport) the program runs in an in-process V8 isolate and no sandbox is needed (see [In-process isolation](#in-process-isolation)).
+
 ## Quickstart
 
-`createCodeMode()` returns the tool plus generated instructions. With no `id`, the tool is named `execute_typescript`. Add both to your agent:
+`createCodeMode()` returns the tool plus generated instructions. With no `id`, the tool uses the name `execute_typescript`. Add both to your agent:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -64,7 +70,7 @@ const agent = new Agent({
   id: 'shop-assistant',
   name: 'shop-assistant',
   instructions: ['You are a helpful shopping assistant.', instructions],
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { execute_typescript: tool },
 })
 ```
@@ -119,7 +125,7 @@ const agent = new Agent({
   id: 'ops-assistant',
   name: 'ops-assistant',
   instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { sales_code: sales.tool, inventory_code: inventory.tool },
 })
 ```
@@ -130,7 +136,7 @@ The generated code for `sales_code` can't call an inventory tool, and the revers
 
 By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/reference/workspace/e2b-sandbox)), where the host paths don't exist.
 
-Remote sandboxes need a transport that writes the program into the sandbox filesystem. For E2B, pass the shipped `E2BCodeModeTransport` as the second argument to `createCodeMode`:
+Remote sandboxes need a transport that writes the program into the sandbox filesystem. For E2B, pass the included `E2BCodeModeTransport` as the second argument to `createCodeMode`:
 
 ```typescript
 import { createCodeMode } from '@mastra/core/tools'
@@ -142,8 +148,25 @@ const { tool, instructions } = createCodeMode(
 )
 ```
 
+## In-process isolation
+
+To get a secure boundary without spawning processes or running a remote sandbox, use [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport) from `@mastra/isolated-vm`. It runs the program in an in-process V8 isolate, so no sandbox is required: the isolate has no filesystem, network, or process access, and its only capabilities are the `external_*` functions bridged back to your tools on the host.
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { IsolatedVmCodeModeTransport } from '@mastra/isolated-vm'
+
+const { tool, instructions } = createCodeMode(
+  { tools }, // no sandbox needed
+  new IsolatedVmCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+`isolated-vm` is a native addon, and on Node.js 20 and later the host process must be started with the `--no-node-snapshot` flag. See the [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport) for setup details.
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
+- [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/guardrails.md

@@ -4,7 +4,7 @@
 
 Mastra provides built-in processors that add security and safety controls to your agent. These processors detect, transform, or block harmful content before it reaches the language model or the user.
 
-For an introduction to how processors work, how to add them to an agent, and how to create custom processors, see [Processors](https://mastra.ai/docs/agents/processors).
+For an introduction to processor behavior and custom processors, including how to add them to an agent, see [Processors](https://mastra.ai/docs/agents/processors).
 
 ## Input processors
 
@@ -12,7 +12,7 @@ Input processors run before user messages reach the language model. They handle
 
 ### Normalize user messages
 
-The `UnicodeNormalizer()` cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols.
+The `UnicodeNormalizer()` cleans and normalizes user input by unifying Unicode characters and standardizing whitespace. It also removes problematic symbols.
 
 ```typescript
 import { UnicodeNormalizer } from '@mastra/core/processors'
@@ -188,7 +188,7 @@ Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) ref
 
 ### Enforce cost limits
 
-The `CostGuardProcessor()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate — metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
+The `CostGuardProcessor()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate, metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
 
 ```typescript
 import { CostGuardProcessor } from '@mastra/core/processors'
@@ -257,7 +257,7 @@ moderation.onViolation = ({ processorId, message, detail }) => {
 }
 ```
 
-The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor — including custom ones — can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `CostGuardProcessor`), the callback also fires on warnings without blocking the request.
+The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `CostGuardProcessor`), the callback also fires on warnings without blocking the request.
 
 Errors thrown by the callback are silently caught to prevent interfering with the processor's main logic.
 
@@ -297,11 +297,11 @@ for await (const chunk of stream.fullStream) {
 
 ## Speed up guardrails
 
-Guardrail processors that use an LLM (moderation, PII detection, prompt injection) add latency to every request. Three techniques reduce this overhead.
+Guardrail processors that use an LLM (moderation, PII detection, prompt injection) add latency to every request. These techniques reduce this overhead.
 
 ### Run guardrails in parallel
 
-By default, processors run sequentially. Guardrails that only `block` (and never mutate messages) are independent and can run at the same time using a [workflow processor](https://mastra.ai/docs/agents/processors).
+By default, processors run sequentially. Guardrails that only `block` (and never mutate messages) are independent and can run using a [workflow processor](https://mastra.ai/docs/agents/processors).
 
 You can also mix `block` and `redact` strategies in a single parallel step. Map to the `redact` branch so its transformed messages carry forward.
 
@@ -384,7 +384,7 @@ outputProcessors: [
 
 ## Related
 
-- [Processors](https://mastra.ai/docs/agents/processors): How processors work, execution order, custom processors, and retry mechanism
+- [Processors](https://mastra.ai/docs/agents/processors): Processor behavior and execution order. Also covers custom processors and retry behavior
 - [`Processor` Interface](https://mastra.ai/reference/processors/processor-interface): API reference for the `Processor` interface
-- [Memory Processors](https://mastra.ai/docs/memory/memory-processors): Processors for message history, semantic recall, and working memory
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors): Processors for message history plus semantic recall and working memory
 - 📹 [Mastra processors and guardrails workshop](https://www.youtube.com/watch?v=4Vpp7xQYvl0)

package/.docs/docs/agents/networks.md

@@ -2,7 +2,7 @@
 
 # Agent networks
 
-> **Deprecated — Use supervisor agents:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
 > See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
@@ -29,7 +29,7 @@ export const routingAgent = new Agent({
   name: 'Routing Agent',
   instructions: `
     You are a network of writers and researchers. The user will ask you to research a topic. Always respond with a complete report—no bullet points. Write in full paragraphs, like a blog post. Do not answer with incomplete or uncertain information.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: {
     researchAgent,
     writingAgent,

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

@@ -2,9 +2,11 @@
 
 # Agents overview
 
-Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or multi-agent systems.
+Agents use LLMs and tools to solve open-ended tasks. They reason about goals and decide which tools to use. They retain conversation memory and continue iterating until the model emits a final answer or an optional stop condition is met.
 
-**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.5`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.
+Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or multi-agent systems.
+
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.6-sol`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.
 
 Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
 
@@ -60,11 +62,11 @@ export const weatherTool = createTool({
 
 If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
 
-By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
 
 Short list of known model IDs are:
 
-- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `openai/gpt-5.6-sol`, `openai/gpt-5-mini`
 - `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
 - `google/gemini-2.5-flash`
 
@@ -92,7 +94,7 @@ export const weatherAgent = new Agent({
       Use the weatherTool to fetch current weather data.
 `,
   // Use a string in provider/model format, not provider:model or a provider object.
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { weatherTool },
 })
 ```
@@ -136,7 +138,7 @@ export const testAgent = new Agent({
   id: 'test-agent',
   name: 'Test Agent',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -157,7 +159,7 @@ Once registered, it can be called from workflows, tools, or other agents, and ha
 
 Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
 
-> **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
+> **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages and inspect tool calls and responses, plus debug agent behavior.
 
 ## Use your agent
 

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

@@ -84,7 +84,7 @@ Memory loads message history first, then your processors run.
 
 Your processors run first, then memory persists messages.
 
-This ordering ensures that if your output guardrail calls `abort()`, memory processors are skipped and no messages are saved. See [Memory Processors](https://mastra.ai/docs/memory/memory-processors) for details.
+With this ordering, an output guardrail that calls `abort()` skips memory processors and prevents messages from being saved. See [Memory Processors](https://mastra.ai/docs/memory/memory-processors) for details.
 
 ## Attach processors to an agent
 
@@ -177,7 +177,7 @@ See the [`Processor` reference](https://mastra.ai/reference/processors/processor
 
 ### Control each step
 
-While `processInput()` runs once at the start of agent execution, `processInputStep()` runs at **each step** of the agentic loop (including tool call continuations). This enables per-step configuration changes like dynamic model switching or tool choice modifications.
+While `processInput()` runs once at the start of agent execution, `processInputStep()` runs at **each step** of the agentic loop (including tool call continuations). It enables per-step configuration changes like runtime model switching or tool choice modifications.
 
 ```typescript
 import type {
@@ -235,7 +235,7 @@ See the [`Processor` reference](https://mastra.ai/reference/processors/processor
 
 Use `processLLMResponse()` to act on the completed LLM response after the step finishes and stream chunks have been collected. This hook pairs with `processLLMRequest()`: stash state (such as a cache key) in the request hook, then read it back in the response hook to perform side effects like writing to a cache.
 
-The `state` object is the same instance passed to `processLLMRequest()` for the same step. When `fromCache` is `true`, the response was replayed from a cache rather than produced by a live model call — processors that write to a cache should skip writes in this case.
+The `state` object is the same instance passed to `processLLMRequest()` for the same step. When `fromCache` is `true`, the response was replayed from a cache rather than produced by a live model call, processors that write to a cache should skip writes in this case.
 
 The method receives `chunks`, `model`, `stepNumber`, `steps`, `state`, `fromCache`, and the shared processor context.
 
@@ -274,7 +274,7 @@ export class CustomOutputProcessor implements Processor {
 }
 ```
 
-The method also receives a `result` object with the full generation data — `text`, `usage` (token counts), `finishReason`, and `steps` (each containing `toolCalls`, `toolResults`, etc.). Use it to track usage or inspect tool calls:
+The method also receives a `result` object with the full generation data, `text`, `usage` (token counts), `finishReason`, and `steps` (each containing `toolCalls`, `toolResults`, etc.). Use it to track usage or inspect tool calls:
 
 ```typescript
 import type { Processor } from '@mastra/core/processors'
@@ -316,7 +316,7 @@ export class StreamFilter implements Processor {
 Return values:
 
 - A `ChunkType` emits that chunk. Return the original `part` to pass it through unchanged.
-- `null` or `undefined` drops the chunk. Both behave the same way, so a method that falls through without returning also drops the chunk.
+- `null` or `undefined` drops the chunk. Both behave the same way, so a method that returns nothing also drops the chunk.
 - Dropping only affects one chunk. To stop the stream entirely, call `abort()`.
 
 To also receive custom `data-*` chunks emitted by tools via `writer.custom()`, set `processDataParts = true` on your processor. This lets you inspect, modify, or block tool-emitted data chunks before they reach the client.
@@ -387,7 +387,7 @@ import { TokenLimiter } from '@mastra/core/processors'
 const agent = new Agent({
   id: 'my-agent',
   name: 'my-agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   inputProcessors: [new TokenLimiter(127000)],
 })
 ```
@@ -418,7 +418,7 @@ See the [`ToolCallFilter` reference](https://mastra.ai/reference/processors/tool
 
 ### `ToolSearchProcessor`
 
-Enables dynamic tool discovery for agents with large tool libraries. Instead of providing all tools upfront, the processor gives the agent `search_tools` and `load_tool` meta-tools to find and load tools by keyword on demand, reducing context token usage.
+Enables runtime tool discovery for agents with large tool libraries. Instead of providing all tools upfront, the processor gives the agent `search_tools` and `load_tool` meta-tools to find and load tools by keyword on demand, reducing context token usage.
 
 See the [`ToolSearchProcessor` reference](https://mastra.ai/reference/processors/tool-search-processor) for configuration options and usage examples.
 
@@ -436,7 +436,7 @@ See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processo
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
-Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. Mastra doesn't provide an agent-level option. To enable caching, register the processor explicitly. This keeps the API surface small while Mastra collects feedback; per-call overrides flow through `RequestContext`.
+Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. Mastra doesn't provide an agent-level option. To enable caching, register the processor explicitly. This keeps the API surface small while Mastra collects feedback. Per-call overrides flow through `RequestContext`.
 
 ### When to use response caching
 
@@ -484,7 +484,7 @@ ResponseCache.applyContext(ctx, { bust: true })
 await agent.stream('hello', { requestContext: ctx })
 ```
 
-Three fields are overridable per call:
+These fields are overridable per call:
 
 - `key`: String or function. Overrides the auto-derived cache key for this request only.
 - `scope`: String or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
@@ -494,7 +494,7 @@ Three fields are overridable per call:
 
 ### Tenant scoping
 
-By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Two users never see each other's cached responses.
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Users never see each other's cached responses.
 
 Override explicitly when you need a different scope:
 
@@ -803,7 +803,7 @@ const moderationWorkflow = createWorkflow({
 const agent = new Agent({
   id: 'moderated-agent',
   name: 'Moderated Agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   inputProcessors: [moderationWorkflow],
 })
 ```
@@ -842,7 +842,7 @@ export class QualityChecker implements Processor {
 const agent = new Agent({
   id: 'quality-agent',
   name: 'Quality Agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   outputProcessors: [new QualityChecker()],
   maxProcessorRetries: 3, // Maximum retry attempts. If unset, retries are disabled (unless errorProcessors are configured, in which case it defaults to 10).
 })
@@ -863,7 +863,7 @@ For `StreamErrorRetryProcessor`, also set its `maxRetries` to the same value. It
 
 ### Violation callbacks
 
-All processors expose an `onViolation` property that fires whenever a policy violation is detected — both when `abort()` is called (block strategy) and when a processor issues a warning (warn strategy). Use it for alerting, logging, or side effects without affecting the processor's main logic:
+All processors expose an `onViolation` property that fires whenever a policy violation is detected, both when `abort()` is called (block strategy) and when a processor issues a warning (warn strategy). Use it for alerting, logging, or side effects without affecting the processor's main logic:
 
 ```typescript
 import { ModerationProcessor, CostGuardProcessor } from '@mastra/core/processors'
@@ -919,7 +919,7 @@ For `agent.generate()`, the result exposes the same information as `result.tripw
 
 ## API error handling
 
-The `processAPIError` method handles LLM API rejections — errors where the API rejects the request (such as 400 or 422 status codes) rather than network or server failures. This lets you modify the request and retry when the API rejects the message format.
+The `processAPIError` method handles LLM API rejections, errors where the API rejects the request (such as 400 or 422 status codes) rather than network or server failures. This lets you modify the request and retry when the API rejects the message format.
 
 ```typescript
 import { APICallError } from '@ai-sdk/provider'
@@ -953,4 +953,4 @@ Mastra includes a built-in [`PrefillErrorHandler`](https://mastra.ai/reference/p
 - [Guardrails](https://mastra.ai/docs/agents/guardrails): Security and validation processors
 - [Memory Processors](https://mastra.ai/docs/memory/memory-processors): Memory-specific processors and automatic integration
 - [Processor Interface](https://mastra.ai/reference/processors/processor-interface): Full API reference for processors
-- [ToolSearchProcessor Reference](https://mastra.ai/reference/processors/tool-search-processor): API reference for dynamic tool search
+- [ToolSearchProcessor Reference](https://mastra.ai/reference/processors/tool-search-processor): API reference for runtime tool search

package/.docs/docs/agents/skills.md

@@ -4,7 +4,7 @@
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
 
-You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/overview). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required; use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach — defining skills in code, loading them from files, and resolving them per request.
+You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/overview). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
 
 ## When to use agent-level skills
 
@@ -12,7 +12,7 @@ Use agent-level skills when:
 
 - You want self-contained agents that don't depend on a workspace
 - Skills are defined in code and don't need filesystem discovery
-- You're building packages or libraries that ship agent capabilities
+- You're building packages or libraries that contain agent capabilities
 - You need per-request skill resolution based on context
 
 For filesystem-based skill discovery across a project, use [workspace skills](https://mastra.ai/docs/workspace/skills) instead.
@@ -38,7 +38,7 @@ const codeReview = createSkill({
 
 export const reviewer = new Agent({
   id: 'reviewer',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   instructions: 'You are a code review assistant.',
   skills: [codeReview],
 })
@@ -81,7 +81,7 @@ import { createSkill } from '@mastra/core/skills'
 
 export const agent = new Agent({
   id: 'my-agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   skills: [
     './skills/code-review', // path to a SKILL.md directory
     './skills/testing', // another filesystem skill
@@ -114,7 +114,7 @@ const supportSkill = createSkill({
 
 export const agent = new Agent({
   id: 'dynamic-agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   skills: ({ requestContext }) => {
     const role = requestContext.get('userRole')
     if (role === 'developer') return [devSkill]
@@ -149,7 +149,7 @@ const customReview = createSkill({
 
 export const reviewer = new Agent({
   id: 'reviewer',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   workspace,
   skills: [customReview], // agent-level "code-review" wins
 })

package/.docs/docs/agents/structured-output.md

@@ -180,7 +180,7 @@ const response = await testAgent.generate('Analyze the TypeScript programming la
         differentiators: z.array(z.string()),
       }),
     }),
-    model: 'openai/gpt-5.5',
+    model: 'openai/gpt-5.6-sol',
   },
 })
 
@@ -251,13 +251,13 @@ Use an explicit mode when you need to override the capability-based choice:
 
 When `model` is provided to the `structuredOutput` property, Mastra uses a separate internal agent to handle the structured output. The main agent will handle all of the steps (including tool calling) and the structured output model will handle only the generation of structured output.
 
-**For AI agents:** The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`, `openai/gpt-5-mini`, `anthropic/claude-sonnet-4-6` or `google/gemini-2.5-pro`. Use `/` and not `:` as a separator. Example: `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise. By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`.
+**For AI agents:** The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.6-sol`, `openai/gpt-5-mini`, `anthropic/claude-sonnet-4-6` or `google/gemini-2.5-pro`. Use `/` and not `:` as a separator. Example: `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise. By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`.
 
 ```typescript
 const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {
     schema: yourSchema,
-    model: 'openai/gpt-5.5',
+    model: 'openai/gpt-5.6-sol',
   },
 })
 ```
@@ -276,7 +276,7 @@ const response = await testAgent.generate('Return my profile as structured data.
       hometown: z.string(),
       petName: z.string(),
     }),
-    model: 'openai/gpt-5.5',
+    model: 'openai/gpt-5.6-sol',
     useAgent: true,
   },
 })
@@ -293,7 +293,7 @@ const result = await agent.stream('weather in vancouver?', {
   prepareStep: async ({ stepNumber }) => {
     if (stepNumber === 0) {
       return {
-        model: 'openai/gpt-5.5',
+        model: 'openai/gpt-5.6-sol',
         tools: {
           weatherTool,
         },
@@ -301,7 +301,7 @@ const result = await agent.stream('weather in vancouver?', {
       }
     }
     return {
-      model: 'openai/gpt-5.5',
+      model: 'openai/gpt-5.6-sol',
       tools: undefined,
       structuredOutput: {
         schema: z.object({