@mastra/core 1.2.0 → 1.2.1-alpha.0

package/dist/docs/{agents/01-overview.md → references/docs-agents-overview.md}

@@ -1,61 +1,65 @@
-> Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
-
-> **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-5HDIPOLV.js:17701
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-EY3WXGUD.js:24
-
 # Using Agents
 
 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 agent networks.
 
-![Agents overview](/img/agents/agents-overview.jpg)
+![Agents overview](/assets/images/agents-overview-1e3bb3b8cf0d13be675394ad41418ea7.jpg)
 
-> **Watch an introduction**
-
-An introduction to agents, and how they compare to workflows on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
+> **Watch an introduction:** An introduction to agents, and how they compare to workflows on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
 ## Setting up agents
+
 ### Installation
 
-### Step
+1. Add the Mastra core package to your project:
 
-Add the Mastra core package to your project:
+   **npm**:
 
-```bash npm2yarn
-npm install @mastra/core@latest
-```
+   ```bash
+   npm install @mastra/core@latest
+   ```
 
-### Step
+   **pnpm**:
 
-Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
+   ```bash
+   pnpm add @mastra/core@latest
+   ```
 
-```bash title=".env"
-OPENAI_API_KEY=<your-api-key>
-```
+   **Yarn**:
 
-> **Note:**
+   ```bash
+   yarn add @mastra/core@latest
+   ```
 
-Mastra supports more than 600 models. Choose from the [full list](/models).
+   **Bun**:
 
-### Step
+   ```bash
+   bun add @mastra/core@latest
+   ```
 
-Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
+2. Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
 
-```typescript title="src/mastra/agents/test-agent.ts"
-import { Agent } from "@mastra/core/agent";
+   ```bash
+   OPENAI_API_KEY=<your-api-key>
+   ```
 
-export const testAgent = new Agent({
-  id: "test-agent",
-  name: "Test Agent",
-  instructions: "You are a helpful assistant.",
-  model: "openai/gpt-5.1",
-});
-```
+   > **Note:** Mastra supports more than 600 models. Choose from the [full list](https://mastra.ai/models).
+
+3. Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
+
+   ```typescript
+   import { Agent } from "@mastra/core/agent";
+
+   export const testAgent = new Agent({
+     id: "test-agent",
+     name: "Test Agent",
+     instructions: "You are a helpful assistant.",
+     model: "openai/gpt-5.1",
+   });
+   ```
 
 ### Instruction formats
 
-Instructions define the agent's behavior, personality, and capabilities.
-They are system-level prompts that establish the agent's core identity and expertise.
+Instructions define the agent's behavior, personality, and capabilities. They are system-level prompts that establish the agent's core identity and expertise.
 
 Instructions can be provided in multiple formats for greater flexibility. The examples below illustrate the supported shapes:
 
@@ -94,23 +98,19 @@ instructions: {
 }
 ```
 
-> **Note:**
-
-Visit [Agent reference](https://mastra.ai/reference/agents/agent) for more information.
+> **Info:** Visit [Agent reference](https://mastra.ai/reference/agents/agent) for more information.
 
 ### Dynamic instructions
 
 Instructions can be provided as an async function, allowing you to resolve prompts at runtime. This enables patterns like personalizing instructions based on user context, fetching prompts from external registry services, and running A/B tests with different variants.
 
-> **Note:**
-
-See [Dynamic instructions](https://mastra.ai/docs/server/request-context#dynamic-instructions) for examples.
+> **Info:** See [Dynamic instructions](https://mastra.ai/docs/server/request-context) for examples.
 
 ### Registering an agent
 
 Register your agent in the Mastra instance to make it available throughout your application. Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features:
 
-```typescript {5} title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { testAgent } from "./agents/test-agent";
 
@@ -127,17 +127,13 @@ You can call agents from workflow steps, tools, the Mastra Client, or the comman
 const testAgent = mastra.getAgent("testAgent");
 ```
 
-:> **Note:**
-
-`mastra.getAgent()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
-
-:
+> **Info:** `mastra.getAgent()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
 
 ## Generating responses
 
 Agents can return results in two ways: generating the full output before returning it or streaming tokens in real time. Choose the approach that fits your use case: generate for short, internal responses or debugging, and stream to deliver pixels to end users as quickly as possible.
 
-  **generate:**
+**Generate**:
 
 Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content`.
 
@@ -157,8 +153,7 @@ const response = await testAgent.generate([
 console.log(response.text);
 ```
 
-  
-  **stream:**
+**Stream**:
 
 Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content`.
 
@@ -180,10 +175,9 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-<h3 id="completion-using-onfinish">Completion using `onFinish()`</h3>
+### Completion using `onFinish()`
 
-When streaming responses, the `onFinish()` callback runs after the LLM finishes generating its response and all tool executions are complete.
-It provides the final `text`, execution `steps`, `finishReason`, token `usage` statistics, and other metadata useful for monitoring or logging.
+When streaming responses, the `onFinish()` callback runs after the LLM finishes generating its response and all tool executions are complete. It provides the final `text`, execution `steps`, `finishReason`, token `usage` statistics, and other metadata useful for monitoring or logging.
 
 ```typescript
 const stream = await testAgent.stream("Help me organize my day", {
@@ -197,19 +191,13 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-  
-
-> **Note:**
-
-Visit [.generate()](https://mastra.ai/reference/agents/generate) or [.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
+> **Info:** Visit [.generate()](https://mastra.ai/reference/agents/generate) or [.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
 ## Structured output
 
 Agents can return structured, type-safe data using Zod or JSON Schema. The parsed result is available on `response.object`.
 
-> **Note:**
-
-Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more information.
+> **Info:** Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more information.
 
 ## Analyzing images
 
@@ -266,7 +254,7 @@ const response = await testAgent.generate("Help me organize my day", {
 
 Agents can use tools to go beyond language generation, enabling structured interactions with external APIs and services. Tools allow agents to access data and perform clearly defined operations in a reliable, repeatable way.
 
-```typescript title="src/mastra/agents/test-agent.ts"
+```typescript
 export const testAgent = new Agent({
   id: "test-agent",
   name: "Test Agent",
@@ -274,15 +262,13 @@ export const testAgent = new Agent({
 });
 ```
 
-> **Note:**
-
-Visit [Using Tools](https://mastra.ai/docs/agents/using-tools) for more information.
+> **Info:** Visit [Using Tools](https://mastra.ai/docs/agents/using-tools) for more information.
 
 ## Using `RequestContext`
 
 Use `RequestContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
-```typescript title="src/mastra/agents/test-agent.ts"
+```typescript
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
@@ -300,13 +286,9 @@ export const testAgent = new Agent({
 });
 ```
 
-> **Note:**
-
-See [Request Context](https://mastra.ai/docs/server/request-context) for more information.
-
-> **Note:**
+> **Info:** See [Request Context](https://mastra.ai/docs/server/request-context) for more information.
 
-For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context#schema-validation).
+> **Tip:** For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context).
 
 ## Testing with Studio
 

package/dist/docs/{agents/06-processors.md → references/docs-agents-processors.md}

@@ -1,5 +1,3 @@
-> Learn how to use input and output processors to transform, validate, and control messages in Mastra agents.
-
 # Processors
 
 Processors transform, validate, or control messages as they pass through an agent. They run at specific points in the agent's execution pipeline, allowing you to modify inputs before they reach the language model or outputs before they're returned to users.
@@ -32,7 +30,7 @@ Mastra includes several processors for common use cases. You can also create cus
 
 Import and instantiate the processor, then pass it to the agent's `inputProcessors` or `outputProcessors` array:
 
-```typescript {2,8-14} title="src/mastra/agents/moderated-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { ModerationProcessor } from "@mastra/core/processors";
 
@@ -70,18 +68,22 @@ For output processors, the order determines the sequence of transformations appl
 When memory is enabled on an agent, memory processors are automatically added to the pipeline:
 
 **Input processors:**
-```
+
+```text
 [Memory Processors] → [Your inputProcessors]
 ```
+
 Memory loads message history first, then your processors run.
 
 **Output processors:**
-```
+
+```text
 [Your outputProcessors] → [Memory Processors]
 ```
+
 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#processor-execution-order) for details.
+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.
 
 ## Creating custom processors
 
@@ -89,7 +91,7 @@ Custom processors implement the `Processor` interface:
 
 ### Custom input processor
 
-```typescript title="src/mastra/processors/custom-input.ts"
+```typescript
 import type {
   Processor,
   MastraDBMessage,
@@ -121,6 +123,7 @@ export class CustomInputProcessor implements Processor {
 ```
 
 The `processInput` method receives:
+
 - `messages`: User and assistant messages (not system messages)
 - `systemMessages`: All system messages (agent instructions, memory context, user-provided system prompts)
 - `messageList`: The full MessageList instance for advanced use cases
@@ -128,6 +131,7 @@ The `processInput` method receives:
 - `requestContext`: Execution metadata like `threadId` and `resourceId`
 
 The method can return:
+
 - `MastraDBMessage[]` — Transformed messages array (backward compatible)
 - `{ messages: MastraDBMessage[]; systemMessages: CoreMessage[] }` — Both messages and modified system messages
 
@@ -137,7 +141,7 @@ The framework handles both return formats, so modifying system messages is optio
 
 To modify system messages (e.g., trim verbose prompts for smaller models), return an object with both `messages` and `systemMessages`:
 
-```typescript title="src/mastra/processors/system-trimmer.ts"
+```typescript
 import type { Processor, CoreMessage, MastraDBMessage } from "@mastra/core";
 
 export class SystemTrimmer implements Processor {
@@ -162,6 +166,7 @@ export class SystemTrimmer implements Processor {
 ```
 
 This is useful for:
+
 - Trimming verbose system prompts for models with smaller context windows
 - Filtering or modifying semantic recall content to prevent "prompt too long" errors
 - Dynamically adjusting system instructions based on the conversation
@@ -170,7 +175,7 @@ This is useful for:
 
 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.
 
-```typescript title="src/mastra/processors/step-processor.ts"
+```typescript
 import type { Processor, ProcessInputStepArgs, ProcessInputStepResult } from "@mastra/core";
 
 export class DynamicModelProcessor implements Processor {
@@ -199,6 +204,7 @@ export class DynamicModelProcessor implements Processor {
 ```
 
 The `processInputStep` method receives:
+
 - `stepNumber`: Current step in the agentic loop (0-indexed)
 - `steps`: Results from previous steps
 - `messages`: Current messages snapshot (read-only)
@@ -213,6 +219,7 @@ The `processInputStep` method receives:
 - `structuredOutput`: Structured output configuration
 
 The method can return any combination of:
+
 - `model`: Change the model for this step
 - `tools`: Replace or add tools (use spread to merge: `{ tools: { ...tools, newTool } }`)
 - `toolChoice`: Change tool selection behavior
@@ -227,7 +234,7 @@ The method can return any combination of:
 
 When using `maxSteps` to limit agent execution, the agent may return an empty response if it attempts a tool call on the final step. Use `processInputStep` to force a text response on the last step:
 
-```typescript title="src/mastra/processors/ensure-final-response.ts"
+```typescript
 import { Processor, ProcessInputStepArgs, ProcessInputStepResult } from "@mastra/core/processors";
 
 export class EnsureFinalResponseProcessor implements Processor {
@@ -262,7 +269,7 @@ export class EnsureFinalResponseProcessor implements Processor {
 
 Use it with your agent:
 
-```typescript title="src/mastra/agents/bounded-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { EnsureFinalResponseProcessor } from "../processors/ensure-final-response";
 
@@ -301,7 +308,7 @@ await agent.generate("Complex task", {
 
 ### Custom output processor
 
-```typescript title="src/mastra/processors/custom-output.ts"
+```typescript
 import type {
   Processor,
   MastraDBMessage,
@@ -339,7 +346,7 @@ export class CustomOutputProcessor implements Processor {
 
 You can add custom metadata to messages in `processOutputResult`. This metadata is accessible via the response object:
 
-```typescript title="src/mastra/processors/metadata-processor.ts"
+```typescript
 import type { Processor, MastraDBMessage } from "@mastra/core";
 
 export class MetadataProcessor implements Processor {
@@ -403,14 +410,13 @@ console.log(response.uiMessages);
 
 Mastra provides utility processors for common tasks:
 
-**For security and validation processors**, see the [Guardrails](https://mastra.ai/docs/agents/guardrails) page for input/output guardrails and moderation processors.
-**For memory-specific processors**, see the [Memory Processors](https://mastra.ai/docs/memory/memory-processors) page for processors that handle message history, semantic recall, and working memory.
+**For security and validation processors**, see the [Guardrails](https://mastra.ai/docs/agents/guardrails) page for input/output guardrails and moderation processors. **For memory-specific processors**, see the [Memory Processors](https://mastra.ai/docs/memory/memory-processors) page for processors that handle message history, semantic recall, and working memory.
 
 ### TokenLimiter
 
 Prevents context window overflow by removing older messages when the total token count exceeds a specified limit.
 
-```typescript {7-10}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { TokenLimiter } from "@mastra/core/processors";
 
@@ -426,7 +432,7 @@ const agent = new Agent({
 
 The `TokenLimiter` uses the `o200k_base` encoding by default (suitable for GPT-4o). You can specify other encodings for different models:
 
-```typescript {6-9}
+```typescript
 import cl100k_base from "js-tiktoken/ranks/cl100k_base";
 
 const agent = new Agent({
@@ -444,7 +450,7 @@ const agent = new Agent({
 
 Removes tool calls from messages sent to the LLM, saving tokens by excluding potentially verbose tool interactions.
 
-```typescript {7-16}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { ToolCallFilter, TokenLimiter } from "@mastra/core/processors";
 
@@ -464,15 +470,13 @@ const agent = new Agent({
 });
 ```
 
-> **Note:**
-
-The example above filters tool calls and limits tokens for the LLM, but these filtered messages will still be saved to memory. To also filter messages before they're saved to memory, manually add memory processors before utility processors. See [Memory Processors](https://mastra.ai/docs/memory/memory-processors#manual-control-and-deduplication) for details.
+> **Note:** The example above filters tool calls and limits tokens for the LLM, but these filtered messages will still be saved to memory. To also filter messages before they're saved to memory, manually add memory processors before utility processors. See [Memory Processors](https://mastra.ai/docs/memory/memory-processors) for details.
 
 ### ToolSearchProcessor
 
 Enables dynamic tool discovery and loading for agents with large tool libraries. Instead of providing all tools upfront, the agent searches for tools by keyword and loads them on demand, reducing context token usage.
 
-```typescript {2,9-18}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { ToolSearchProcessor } from "@mastra/core/processors";
 
@@ -498,7 +502,7 @@ The processor gives the agent two meta-tools: `search_tools` to find tools by ke
 
 You can use Mastra workflows as processors to create complex processing pipelines with parallel execution, conditional branching, and error handling:
 
-```typescript title="src/mastra/processors/moderation-workflow.ts"
+```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { ProcessorStepSchema } from "@mastra/core/processors";
 import { Agent } from "@mastra/core/agent";
@@ -531,7 +535,7 @@ When an agent is registered with Mastra, processor workflows are automatically r
 
 Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks, output validation, or iterative refinement:
 
-```typescript title="src/mastra/processors/quality-checker.ts"
+```typescript
 import type { Processor } from "@mastra/core";
 
 export class QualityChecker implements Processor {
@@ -562,6 +566,7 @@ const agent = new Agent({
 ```
 
 The retry mechanism:
+
 - Only works in `processOutputStep` and `processInputStep` methods
 - Replays the step with the abort reason added as context for the LLM
 - Tracks retry count via the `retryCount` parameter

package/dist/docs/{agents/04-structured-output.md → references/docs-agents-structured-output.md}

@@ -1,5 +1,3 @@
-> Learn how to generate structured data from agents using schemas and validation.
-
 # Structured Output
 
 Structured output lets an agent return an object that matches the shape defined by a schema instead of returning text. The schema tells the model what fields to produce, and the model ensures the final result fits that shape.
@@ -12,7 +10,7 @@ Use structured output when you need an agent to return a data object rather than
 
 Agents can return structured data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). Zod is recommended because it provides TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
 
-  **zod:**
+**Zod**:
 
 Define the `output` shape using [Zod](https://zod.dev/):
 
@@ -33,8 +31,7 @@ const response = await testAgent.generate("Help me plan my day.", {
 console.log(response.object);
 ```
 
-  
-  **json-schema:**
+**JSON Schema**:
 
 You can also use JSON Schema to define your output structure:
 
@@ -61,11 +58,7 @@ const response = await testAgent.generate("Help me plan my day.", {
 console.log(response.object);
 ```
 
-  
-
-> **Note:**
-
-Visit [.generate()](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
+> **Info:** Visit [.generate()](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
 
 ### Example output
 
@@ -193,18 +186,16 @@ const response = await testAgent.generate("Help me plan my day.", {
 console.log(response.object);
 ```
 
-> **Gemini 2.5 with tools**
-
-Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
-
-```typescript
-const response = await agentWithTools.generate("Your prompt", {
-  structuredOutput: {
-    schema: yourSchema,
-    jsonPromptInjection: true,  // Required for Gemini 2.5 when tools are present
-  },
-});
-```
+> **Gemini 2.5 with tools:** Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
+>
+> ```typescript
+> const response = await agentWithTools.generate("Your prompt", {
+>   structuredOutput: {
+>     schema: yourSchema,
+>     jsonPromptInjection: true,  // Required for Gemini 2.5 when tools are present
+>   },
+> });
+> ```
 
 ### Using a separate structuring model
 

package/dist/docs/{agents/02-using-tools.md → references/docs-agents-using-tools.md}

@@ -1,5 +1,3 @@
-> Learn how to create tools and add them to agents to extend capabilities beyond text generation.
-
 # Using Tools
 
 Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
@@ -14,7 +12,7 @@ When creating tools, keep descriptions simple and focused on what the tool does,
 
 This example shows how to create a tool that fetches weather data from an API. When the agent calls the tool, it provides the required input as defined by the tool's `inputSchema`. The tool accesses this data through its `inputData` parameter, which in this example includes the `location` used in the weather API query.
 
-```typescript title="src/mastra/tools/weather-tool.ts"
+```typescript
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
@@ -44,7 +42,7 @@ To make a tool available to an agent, add it to `tools`. Mentioning available to
 
 An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
 
-```typescript {11} title="src/mastra/agents/weather-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
@@ -89,10 +87,10 @@ This lets you specify how tools are identified in the stream. If you want the `t
 
 Sub-agents and workflows follow the same pattern. They are converted to tools with a prefix followed by your object key:
 
-| Property | Prefix | Example key | `toolName` |
-|----------|--------|-------------|------------|
-| `agents` | `agent-` | `weather` | `agent-weather` |
-| `workflows` | `workflow-` | `research` | `workflow-research` |
+| Property    | Prefix      | Example key | `toolName`          |
+| ----------- | ----------- | ----------- | ------------------- |
+| `agents`    | `agent-`    | `weather`   | `agent-weather`     |
+| `workflows` | `workflow-` | `research`  | `workflow-research` |
 
 ```typescript
 const orchestrator = new Agent({
@@ -107,6 +105,7 @@ const orchestrator = new Agent({
 ```
 
 Note that for sub-agents, you'll see two different identifiers in stream responses:
+
 - `toolName: "agent-weather"` in tool call events — the generated tool wrapper name
 - `id: "weather-agent"` in `data-tool-agent` chunks — the sub-agent's actual `id` property
 
@@ -114,7 +113,7 @@ Note that for sub-agents, you'll see two different identifiers in stream respons
 
 The agent uses the tool's `inputSchema` to infer what data the tool expects. In this case, it extracts `London` as the `location` from the message and passes it to the tool's inputData parameter.
 
-```typescript title="src/test-tool.ts"
+```typescript
 import { mastra } from "./mastra";
 
 const agent = mastra.getAgent("weatherAgent");
@@ -126,7 +125,7 @@ const result = await agent.generate("What's the weather in London?");
 
 When multiple tools are available, the agent may choose to use one, several, or none, depending on what's needed to answer the query.
 
-```typescript {7} title="src/mastra/agents/weather-agent.ts"
+```typescript
 import { weatherTool } from "../tools/weather-tool";
 import { activitiesTool } from "../tools/activities-tool";
 
@@ -141,7 +140,7 @@ export const weatherAgent = new Agent({
 
 Workflows can be added to agents through the `workflows` configuration. When you add a workflow, Mastra automatically converts it to a tool that the agent can call. The generated tool is named `workflow-<workflowName>` and uses the workflow's `inputSchema` and `outputSchema`.
 
-```typescript {14-16} title="src/mastra/agents/research-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { researchWorkflow } from "../workflows/research-workflow";
 
@@ -163,7 +162,7 @@ export const researchAgent = new Agent({
 
 The workflow should include a `description` to help the agent understand when to use it:
 
-```typescript title="src/mastra/workflows/research-workflow.ts"
+```typescript
 import { createWorkflow } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -194,7 +193,7 @@ When the agent calls the workflow tool, it receives a response containing the wo
 
 ## Tools with structured output
 
-When using tools with [structured output](https://mastra.ai/docs/agents/structured-output), some models don't support combining both features in the same API call. If your tools aren't being called when structured output is enabled, or you receive errors about incompatible options, see [Combining tools and structured output](https://mastra.ai/docs/agents/structured-output#combining-tools-and-structured-output) for model compatibility information and workarounds.
+When using tools with [structured output](https://mastra.ai/docs/agents/structured-output), some models don't support combining both features in the same API call. If your tools aren't being called when structured output is enabled, or you receive errors about incompatible options, see [Combining tools and structured output](https://mastra.ai/docs/agents/structured-output) for model compatibility information and workarounds.
 
 ## Related
 

package/dist/docs/{evals/02-custom-scorers.md → references/docs-evals-custom-scorers.md}

@@ -281,11 +281,9 @@ A custom scorer in Mastra uses `createScorer` with four core components:
 
 Together, these components allow you to define custom evaluation logic using LLMs as judges.
 
-> **Note:**
+> **Info:** Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
 
-Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
-
-```typescript title="src/mastra/scorers/gluten-checker.ts"
+```typescript
 import { createScorer } from "@mastra/core/evals";
 import { z } from "zod";
 
@@ -439,7 +437,7 @@ The reason generation step creates explanations that help users understand why a
 
 ## High gluten-free example
 
-```typescript title="src/example-high-gluten-free.ts"
+```typescript
 const result = await glutenCheckerScorer.run({
   input: [{ role: 'user', content: 'Mix rice, beans, and vegetables' }],
   output: { text: 'Mix rice, beans, and vegetables' },
@@ -465,7 +463,7 @@ console.log('Reason:', result.reason);
 
 ## Partial gluten example
 
-```typescript title="src/example-partial-gluten.ts"
+```typescript
 const result = await glutenCheckerScorer.run({
   input: [{ role: "user", content: "Mix flour and water to make dough" }],
   output: { text: "Mix flour and water to make dough" },
@@ -491,7 +489,7 @@ console.log("Reason:", result.reason);
 
 ## Low gluten-free example
 
-```typescript title="src/example-low-gluten-free.ts"
+```typescript
 const result = await glutenCheckerScorer.run({
   input: [{ role: "user", content: "Add soy sauce and noodles" }],
   output: { text: "Add soy sauce and noodles" },