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

package/.docs/docs/deployment/workers.md

@@ -0,0 +1,137 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workers
+
+> **Beta:** This feature is in beta. The API is stable enough for production use, but some details may change. See [known limitations](#known-limitations) for current gaps.
+
+Workers handle background processing outside the request-response cycle. Workflow step execution, cron-based scheduling, and long-running tool calls all run in workers, keeping the API responsive.
+
+By default, workers run in the same process as the API. For production workloads, you can split them into separate processes or containers and scale each one independently.
+
+## When to use workers
+
+Workers matter when any of these apply:
+
+- Workflow steps take more than a few seconds and shouldn't block API responses
+- You need event durability so in-flight work survives process restarts
+- Different parts of the system need to scale independently (e.g., more orchestration capacity without more API instances)
+- Background tool calls should run on dedicated compute
+
+If your application handles light traffic and workflows complete quickly, the default in-process setup works fine. Skip the worker infrastructure until you need it.
+
+## Worker types
+
+Mastra has three built-in worker types. Each handles a specific kind of background processing.
+
+### Orchestration worker
+
+Subscribes to workflow events on the [PubSub](https://mastra.ai/docs/server/pubsub) bus and executes workflow steps. Every `workflow.start`, step transition, and lifecycle event flows through this worker.
+
+In a split deployment, the orchestration worker pulls events from a distributed PubSub backend and delegates step execution back to the API over HTTP. In-process, it runs steps directly.
+
+The orchestration worker requires a PubSub backend that supports pull mode (e.g., [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)).
+
+### Scheduler worker
+
+Polls storage for due cron schedules and publishes `workflow.start` events. It is a producer only, meaning it creates work for the orchestration worker to pick up.
+
+The scheduler reads declarative `schedule` fields from your workflow definitions automatically. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for how to declare schedules.
+
+**Do not run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
+
+### Background task worker
+
+Executes agent tool calls marked with `background: { enabled: true }`. When an agent invokes a background tool, the API dispatches the task to this worker instead of blocking the response stream.
+
+The background task worker manages concurrency limits, task lifecycle, and result delivery through the PubSub bus.
+
+## How workers run
+
+### In-process (default)
+
+With no configuration, Mastra creates and starts workers inside the API process. Events flow through an in-memory PubSub, and everything shares a single Node.js runtime.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+
+export const mastra = new Mastra({
+  // Workers run in-process by default.
+  // No pubsub or worker config needed.
+})
+```
+
+This setup needs no external infrastructure beyond your storage adapter. It doesn't survive process crashes, and you can't scale individual components.
+
+### Split processes
+
+To run workers separately, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
+
+**Redis Streams + PostgreSQL**:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+import { PostgresStore } from '@mastra/pg'
+
+export const mastra = new Mastra({
+  storage: new PostgresStore({
+    connectionString: process.env.DATABASE_URL!,
+  }),
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL!,
+  }),
+})
+```
+
+**Google Cloud Pub/Sub + LibSQL**:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    url: process.env.DATABASE_URL!,
+  }),
+  pubsub: new GoogleCloudPubSub({
+    projectId: process.env.GCP_PROJECT_ID!,
+  }),
+})
+```
+
+Any [supported storage backend](https://mastra.ai/reference/workers/overview) works — swap the storage adapter for your preferred database.
+
+Run the same build artifact in multiple containers, each with a different [`MASTRA_WORKERS`](https://mastra.ai/reference/workers/overview) value to control which worker starts in each process.
+
+Split deployments require a distributed PubSub backend ([`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)), a shared [storage backend](https://mastra.ai/reference/workers/overview), and network connectivity between the orchestration worker and the API.
+
+The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with a Docker Compose example.
+
+## Network architecture
+
+Workers are internal infrastructure. They are not exposed to end users and do not need their own subdomain, public URL, or inbound HTTP route.
+
+In a split deployment:
+
+- **The API server is the only public-facing process.** It serves all client HTTP requests — REST endpoints, agent interactions, workflow triggers, and any custom routes.
+- **Workers connect outbound only.** They pull events from the distributed PubSub backend and read/write to the shared storage database. They do not accept inbound traffic from clients.
+- **The orchestration worker calls the API internally.** It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
+
+All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. If a worker-related feature needs an HTTP route (for example, token minting for a voice integration), that route runs on the API server, not on the worker process.
+
+## Known limitations
+
+- **No dead-letter queue**: Failed events are nacked and retried, but there is no DLQ for events that repeatedly fail.
+- **No built-in health endpoint**: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
+- **Scheduler is single-instance**: Running multiple scheduler processes causes duplicate schedule fires.
+- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents) for details.
+
+## Related
+
+- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose example and topology options
+- [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
+- [Workers reference](https://mastra.ai/reference/workers/overview): Environment variables, worker types, and storage backends
+- [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
+- [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): Declare cron schedules on workflows

package/.docs/docs/editor/overview.md

@@ -14,9 +14,9 @@ The editor manages two types of resources alongside agents:
 Use the editor when you want to:
 
 - **Let non-developers iterate**: Give subject-matter experts and prompt engineers a way to tune agent behavior without touching code or waiting for deploys.
-- **Version everything**: Every save creates a snapshot so you can compare changes, roll back instantly, and audit what changed and when.
-- **Run experiments**: Route different users or requests to different agent versions for A/B testing, canary rollouts, or prompt experimentation.
-- **Target specific versions**: Pin a version per request, per user, or per environment so production stays stable while new versions are tested.
+- **Version everything**: Every save creates a snapshot so you can compare changes and roll back instantly, plus audit what changed and when.
+- **Run experiments**: Route different users or requests to different agent versions for A/B testing or canary rollouts, or alternatively prompt experimentation.
+- **Target specific versions**: Pin a version per request or per user, or alternatively per environment so production stays stable while new versions are tested.
 - **Manage tools at runtime**: Add integration tools from Composio or Arcade, or connect MCP servers, without updating code.
 - **Override code agents**: Change the instructions, tools, or variables of a code-defined agent while keeping the original code as the baseline.
 
@@ -95,7 +95,7 @@ When `source` is `'code'`, the editor writes each override to a deterministic JS
 
 The code source uses the Git history of each per-agent JSON file as its version history. Each commit that changes a file is shown as a read-only version in Studio, labeled with the commit message. Saving in Studio updates the working file in place rather than creating a database draft, so the version dropdown reflects your actual commit history.
 
-This means versions and rollbacks are managed through Git rather than through draft and publish actions.
+As a result, versions and rollbacks are managed through Git rather than through draft and publish actions.
 
 ## Studio
 
@@ -105,7 +105,7 @@ Modify the system prompt and save a new draft version. Afterwards, publish the d
 
 ## Programmatic control
 
-Everything you can do in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor). This is useful for scripting bulk updates, seeding stored configurations from code, or building automation that tunes agents based on evaluation results.
+Everything you can do in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor). This is useful for scripting bulk updates or seeding stored configurations from code, or alternatively building automation that tunes agents based on evaluation results.
 
 Call `mastra.getEditor()` from anywhere you have access to the `Mastra` instance. It returns the `MastraEditor` instance you registered, with namespaces for each resource type:
 
@@ -167,7 +167,7 @@ Because stored agents are data, you can build automation loops that tune agents
 - Re-run the experiment against the draft and compare scores to the baseline.
 - Promote the draft to the published version when the scores improve.
 
-This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
+This turns agent tuning into a closed feedback loop. One agent owns the production configuration and another agent iterates on it, plus every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
 
 ## What can be overridden
 
@@ -190,7 +190,7 @@ import { Agent } from '@mastra/core/agent'
 export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'support-agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   editor: { instructions: true, tools: { description: true } },
 })
 ```
@@ -209,50 +209,56 @@ When a field is owned by code, Studio shows it as read-only and the server strip
 
 ## Versioning
 
-Every time you save changes to an agent or prompt block, a new version snapshot is created. Versions give you a full history of your agent's configuration. You can roll back to any previous state, compare what changed between two snapshots, and target specific versions per request for A/B testing or gradual rollouts.
+Every time you save changes to an agent or prompt block, a new version snapshot is created. Versions give you a full history of your agent's configuration. You can roll back to any previous state and compare what changed between two snapshots, plus target specific versions per request for A/B testing or gradual rollouts.
 
 Version management is available through the server Studio, REST API, the Client SDK, and the React SDK. See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for endpoints, SDK methods, and code examples.
 
 ### Version lifecycle
 
-Each version has one of three statuses:
+Version snapshots don't store a lifecycle status. Instead, the agent or prompt block stores an `activeVersionId` that identifies its published version.
 
-| Status    | Description                                                                         |
-| --------- | ----------------------------------------------------------------------------------- |
-| Draft     | The latest working copy. Every save creates a new draft version.                    |
-| Published | The active version used in production. Only one version can be published at a time. |
-| Archived  | A previous version that's no longer active. You can restore any archived version.   |
+| Term       | Description                                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Latest     | The most recently saved version snapshot.                                                                                           |
+| Published  | The version whose ID matches `activeVersionId`. Only one version can be active at a time.                                           |
+| Draft      | The latest version when it differs from the active version. If `activeVersionId` isn't set, the latest version remains unpublished. |
+| Historical | Any other saved version. Historical versions remain available for comparison, direct selection, and restoration.                    |
 
-The typical flow is: Edit the draft, test it, then activate it to make it the published version. The previously published version becomes archived so you can restore it if needed. You can do this through Studio or programmatically through the API.
+Saving a database-backed resource creates a new latest version. If an active version already exists, it continues to handle requests until you publish the new version. Publishing sets `activeVersionId` to the selected version without deleting or changing the previous active version.
 
-This lifecycle makes it safe to experiment. Non-technical team members can iterate on a draft without affecting production traffic, then publish when ready. If something goes wrong, restoring a previous version is a single API call.
+Restoring a historical version copies its configuration into a new draft that remains inactive until you publish it.
 
 ### Version targeting and experimentation
 
-Because every version has a unique ID, you can route different requests to different agent configurations. This opens up several patterns:
+Because every version has a unique ID, you can route different requests to different agent configurations. This supports several patterns:
 
-- **A/B testing**: Split traffic between two published versions and compare performance metrics.
-- **Canary rollouts**: Send a small percentage of requests to a new version before promoting it.
-- **Per-user targeting**: Pin specific users or accounts to a version while others use the default.
-- **Environment separation**: Use the draft version in staging and the published version in production.
+- **A/B testing**: Split traffic between specific version IDs and compare performance metrics.
+- **Canary rollouts**: Send a small percentage of requests to a draft or historical version before publishing it.
+- **Per-user targeting**: Pin specific users or accounts to a version while others use the active version.
+- **Environment separation**: Use the latest version in staging and the active version in production.
 
-Pass a `versionId` or `status` when calling the agent through the Client SDK, server query parameters, or React SDK `requestContext`, and the correct version is loaded automatically.
+Pass a `versionId` or `status` when calling the agent through the Client SDK, server query parameters, or React SDK `requestContext`. A `versionId` selects that exact snapshot, `status: 'draft'` selects the latest snapshot, and `status: 'published'` selects the active snapshot.
 
 ### Version selection
 
-By default, [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) loads the published (active) version of the stored override. You can request a specific version, which is useful for testing a draft before publishing, running A/B experiments, or pinning a user to a known-good configuration:
+Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a version selector returns the registered code-defined agent. Pass a selector to apply a published, draft, or specific stored override:
 
 ```typescript
-// Load the published version (default)
-const agent = mastra.getAgentById('support-agent')
+// Load the registered code-defined agent without stored overrides
+const codeAgent = mastra.getAgentById('support-agent')
 
-// Load the latest draft
-const agent = mastra.getAgentById('support-agent', {
+// Load the active published override
+const publishedAgent = await mastra.getAgentById('support-agent', {
+  status: 'published',
+})
+
+// Load the latest override
+const draftAgent = await mastra.getAgentById('support-agent', {
   status: 'draft',
 })
 
 // Load a specific version
-const agent = mastra.getAgentById('support-agent', {
+const versionedAgent = await mastra.getAgentById('support-agent', {
   versionId: 'abc-123',
 })
 ```
@@ -278,9 +284,9 @@ When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) deleg
 
 Set version overrides at three levels, with later levels taking priority:
 
-1. **Mastra instance config** — global defaults that apply to every `generate()` and `stream()` call.
-2. **Per-invocation options** — overrides passed directly to `generate()` or `stream()`.
-3. **Server request body** — overrides sent in the `versions` field of an API request.
+1. **Mastra instance config**: global defaults that apply to every `generate()` and `stream()` call.
+2. **Per-invocation options**: overrides passed directly to `generate()` or `stream()`.
+3. **Server request body**: overrides sent in the `versions` field of an API request.
 
 Resolution order: **per-invocation > request body > Mastra instance defaults > code-defined agent**.
 

package/.docs/docs/editor/prompts.md

@@ -2,7 +2,11 @@
 
 # Prompts
 
-Prompt blocks are reusable instruction templates that you compose into an agent's system prompt. Each block can contain plain text, template variables, and display conditions. Non-technical team members can edit prompt content, test different phrasings, and publish changes. Every edit is versioned, so you can compare prompt variations, roll back, and track what changed over time. You can create and manage prompt blocks through the Studio UI or programmatically through the server API, then reference them across multiple agents.
+Prompt blocks are reusable instruction templates that you compose into an agent's system prompt. Each block can contain plain text, template variables, and display conditions.
+
+Non-technical team members can edit and test prompt content before publishing changes. Every edit is versioned, so you can compare prompt variations and roll back. The history also records what changed over time.
+
+You can create and manage prompt blocks through the Studio UI or programmatically through the server API, then reference them across multiple agents.
 
 ## Quickstart
 
@@ -28,7 +32,7 @@ To turn an inline block into a reusable prompt block, open the block's menu and
 
 ## Template variables
 
-Prompt blocks support `{{variable}}` syntax for dynamic content. Variables are resolved at runtime from the agent's variables and request context.
+Prompt blocks support `{{variable}}` syntax for runtime content. Variables are resolved at runtime from the agent's variables and request context.
 
 ```text
 You are helping {{userName}} with their {{task || 'request'}}.
@@ -63,7 +67,7 @@ In the Studio, open a block's **Display conditions** panel to set up rules visua
 
 ## Programmatic control
 
-Prompt blocks can be managed from code through [`mastra.getEditor().prompt`](https://mastra.ai/reference/editor/mastra-editor). This is useful for seeding a set of starter prompts, syncing blocks between environments, or generating prompt variants from a script.
+Prompt blocks can be managed from code through [`mastra.getEditor().prompt`](https://mastra.ai/reference/editor/mastra-editor). This is useful for seeding a set of starter prompts or syncing blocks between environments, or alternatively generating prompt variants from a script.
 
 Create a new prompt block with `editor.prompt.create()`:
 
@@ -126,7 +130,7 @@ See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-edito
 
 ## Versioning
 
-Prompt blocks follow the same [versioning lifecycle](https://mastra.ai/docs/editor/overview) as agents. Each prompt block has a draft that you can edit and publish as a versioned snapshot. This means prompt content can be versioned and rolled back independently from the agent that uses it.
+Prompt blocks follow the same [versioning lifecycle](https://mastra.ai/docs/editor/overview) as agents. Each prompt block has a draft that you can edit and publish as a versioned snapshot. As a result, prompt content can be versioned and rolled back independently from the agent that uses it.
 
 When an agent references a prompt block, the resolved content comes from the block's active published version by default. During editing, draft content is used for previews. This separation makes it safe for non-technical team members to experiment with prompt wording. The published version stays stable until they explicitly activate a new one.
 

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

@@ -8,7 +8,7 @@ The editor gives you three ways to add tools to agents:
 - **Integration providers**: Third-party tool platforms like Composio and Arcade.
 - **MCP clients**: Tools from MCP servers, configured as reusable client definitions.
 
-You can manage all three sources through the Studio UI or programmatically through the server API. Non-technical team members can browse tool catalogs, add tools to agents, and test different tool combinations without code changes. Tool configurations are versioned alongside the rest of the agent, so you can roll back tool changes, compare versions, and experiment safely.
+You can manage all three sources through the Studio UI or programmatically through the server API. Non-technical team members can browse tool catalogs and add tools to agents, plus test different tool combinations without code changes. Tool configurations are versioned alongside the rest of the agent, so you can roll back tool changes and compare versions, plus experiment safely.
 
 ## Description overrides
 
@@ -24,7 +24,7 @@ In the Studio, select a tool in the agent's tool list and edit the **Description
 
 ## Display conditions
 
-Each tool in an agent can have display conditions — rule groups that control whether the tool is available at runtime. This uses the same rule system as [prompt blocks](https://mastra.ai/docs/editor/prompts).
+Each tool in an agent can have display conditions, rule groups that control whether the tool is available at runtime. This uses the same rule system as [prompt blocks](https://mastra.ai/docs/editor/prompts).
 
 When a request comes in, the editor evaluates each tool's rules against the current context (agent variables and request context). Tools whose conditions aren't met are excluded from that run.
 
@@ -124,7 +124,7 @@ You can filter MCP tools at two levels:
 
 ### Tool namespacing
 
-Tools from MCP servers are namespaced as `serverName_toolName` to avoid conflicts. For example, a tool called `search` from a server named `docs` becomes `docs_search`.
+Tools from MCP servers are namespaced as `serverName_toolName` to avoid conflicts. For example, a `search` tool from the `docs` server becomes `docs_search`.
 
 ### Conditional activation
 

package/.docs/docs/evals/built-in-scorers.md

@@ -2,7 +2,7 @@
 
 # Built-in scorers
 
-Mastra provides a comprehensive set of built-in scorers for evaluating AI outputs. These scorers are optimized for common evaluation scenarios and are ready to use in your agents and workflows.
+Mastra provides a complete set of built-in scorers for evaluating AI outputs. These scorers are optimized for common evaluation scenarios and are ready to use in your agents and workflows.
 
 To create your own scorers, see the [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide.
 
@@ -20,15 +20,15 @@ These scorers evaluate how correct, truthful, and complete your agent's answers
 - [`content-similarity`](https://mastra.ai/reference/evals/content-similarity): Measures textual similarity using character-level matching (`0-1`, higher is better)
 - [`textual-difference`](https://mastra.ai/reference/evals/textual-difference): Measures textual differences between strings (`0-1`, higher means more similar)
 - [`tool-call-accuracy`](https://mastra.ai/reference/evals/tool-call-accuracy): Evaluates whether the LLM selects the correct tool from available options (`0-1`, higher is better)
-- [`trajectory-accuracy`](https://mastra.ai/reference/evals/trajectory-accuracy): Evaluates whether an agent follows the expected sequence of actions (tool calls, model generations, workflow steps, and other span types) (`0-1`, higher is better)
+- [`trajectory-accuracy`](https://mastra.ai/reference/evals/trajectory-accuracy): Evaluates the expected action sequence for all span types. Covered spans include tool and model activity plus workflow steps (`0-1`, higher is better)
 - [`prompt-alignment`](https://mastra.ai/reference/evals/prompt-alignment): Measures how well agent responses align with user prompt intent, requirements, completeness, and format (`0-1`, higher is better)
 
 ### Context quality
 
 These scorers evaluate the quality and relevance of context used in generating responses:
 
-- [`context-precision`](https://mastra.ai/reference/evals/context-precision): Evaluates context relevance and ranking using Mean Average Precision, rewarding early placement of relevant context (`0-1`, higher is better)
-- [`context-relevance`](https://mastra.ai/reference/evals/context-relevance): Measures context utility with nuanced relevance levels, usage tracking, and missing context detection (`0-1`, higher is better)
+- [`context-precision`](https://mastra.ai/reference/evals/context-precision): Uses Mean Average Precision to evaluate context ranking. Relevant context receives a higher score when it occurs early (`0-1`, higher is better)
+- [`context-relevance`](https://mastra.ai/reference/evals/context-relevance): Measures context utility through relevance levels and usage tracking. It also detects missing context (`0-1`, higher is better)
 
 > **Context Scorer Selection:**
 >

package/.docs/docs/evals/custom-scorers.md

@@ -46,7 +46,7 @@ const glutenCheckerScorer = createScorer({
   id: 'gluten-checker',
   description: 'Check if recipes contain gluten ingredients',
   judge: {                    // Optional: for prompt object steps
-    model: 'openai/gpt-5.5',
+    model: 'openai/gpt-5.6-sol',
     instructions: 'You are a Chef that identifies if recipes contain gluten.'
   }
 })
@@ -119,7 +119,7 @@ const myScorer = createScorer({
 
 ### preprocess Step (Optional)
 
-Prepares input/output data when you need to extract specific elements, filter content, or transform complex data structures.
+Prepares input/output data when you need to extract specific elements or filter content, or alternatively transform complex data structures.
 
 **Functions:** `({ run, results }) => any`
 
@@ -274,7 +274,7 @@ const glutenCheckerScorer = createScorer({...})
 
 ## Input filtering
 
-Agent conversations can contain hundreds of messages with tool calls, data parts, and system metadata. Most scorers only need a subset of this data. The `prepareRun` option transforms the run data before the scorer pipeline executes, reducing noise and keeping scorers focused.
+Agent conversations can contain hundreds of messages with tool calls and data parts, plus system metadata. Most scorers only need a subset of this data. The `prepareRun` option transforms the run data before the scorer pipeline executes, reducing noise and keeping scorers focused.
 
 ### Declarative filtering with `filterRun()`
 
@@ -463,7 +463,7 @@ The analysis step uses a prompt object to:
 
 - Provide a clear description of the analysis task
 - Define expected output structure with a Standard JSON Schema (both boolean result and list of gluten sources)
-- Generate dynamic prompts based on the input content
+- Generate runtime prompts based on the input content
 
 ### Score Generation
 
@@ -493,7 +493,7 @@ Provides human-readable explanations for the score using another LLM call.
 })
 ```
 
-The reason generation step creates explanations that help users understand why a particular score was assigned, using both the boolean result and the specific gluten sources identified by the analysis step.
+The reason generation step creates explanations that help users understand why a score was assigned, using both the boolean result and the specific gluten sources identified by the analysis step.
 
 ## High gluten-free example
 

package/.docs/docs/evals/datasets/running-experiments.md

@@ -154,13 +154,13 @@ Tool mocks are supported for `agent` targets only.
 
 ### Matching and consumption
 
-Arguments are matched strictly: object key order is ignored, array order is significant, and there is no type coercion. A mock is served only when the agent calls the tool with arguments that deep-equal the mock's `args`.
+Arguments are matched strictly: object key order is ignored and array order is substantial, plus there is no type coercion. A mock is served only when the agent calls the tool with arguments that deep-equal the mock's `args`.
 
-When an item declares several mocks for the same tool and arguments, they're consumed in order — the first call gets the first mock, the next call gets the second, and so on. Ordering is tracked per `(toolName, args)` group and is independent across different arguments.
+When an item declares several mocks for the same tool and arguments, they're consumed in order, the first call gets the first mock, the next call gets the second, and so on. Ordering is tracked per `(toolName, args)` group and is independent across different arguments.
 
 ### Matching mode
 
-By default each mock matches strictly on its `args`. Set `matchArgs: 'ignore'` to match on the tool name only — the mock's `args` aren't compared and the next unconsumed mock for that tool is served regardless of how the agent called it:
+By default each mock matches strictly on its `args`. Set `matchArgs: 'ignore'` to match on the tool name only, the mock's `args` aren't compared and the next unconsumed mock for that tool is served regardless of how the agent called it:
 
 ```typescript
 const subAgentMock = {
@@ -171,16 +171,16 @@ const subAgentMock = {
 }
 ```
 
-This is useful when a tool's arguments are noisy or generated by the model. The most common case is mocking a **sub-agent's response**: a delegated sub-agent is exposed to the parent as a tool named `agent-<name>`, and its arguments include an LLM-authored `prompt` plus runtime-injected fields. Mocking `agent-<name>` returns the canned response in place of running the sub-agent and its inner tools. When you create a mock from a trace, sub-agent delegation calls are derived with `matchArgs: 'ignore'` automatically; you can change it to `'strict'` to pin the exact arguments.
+This is useful when a tool's arguments are noisy or generated by the model. The most common case is mocking a **sub-agent's response**: a delegated sub-agent is exposed to the parent as an `agent-<name>` tool, and its arguments include an LLM-authored `prompt` plus runtime-injected fields. Mocking `agent-<name>` returns the canned response in place of running the sub-agent and its inner tools. When you create a mock from a trace, sub-agent delegation calls are derived with `matchArgs: 'ignore'` automatically. You can change it to `'strict'` to pin the exact arguments.
 
 ### Failures
 
 A mocked tool call fails the item when the arguments don't match or all matching mocks have been consumed:
 
-- `TOOL_MOCK_MISMATCH` — the tool was called with arguments that no mock matches.
-- `TOOL_MOCK_EXHAUSTED` — every matching mock has already been consumed.
+- `TOOL_MOCK_MISMATCH`: the tool was called with arguments that no mock matches.
+- `TOOL_MOCK_EXHAUSTED`: every matching mock has already been consumed.
 
-When a mocked tool is mis-called, the agent run is aborted immediately, so the model can't go on to call any further tools — including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they're not retried. Mocks that are declared but never used don't fail the item — they're reported as unconsumed.
+When a mocked tool is mis-called, the agent run is aborted immediately, so the model can't go on to call any further tools, including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they're not retried. Mocks that are declared but never used don't fail the item, they're reported as unconsumed.
 
 While an item has mocks, the agent's tools execute sequentially so repeated `(toolName, args)` mocks are consumed in the provider's call order. This serialization applies only to items that declare mocks.
 

package/.docs/docs/evals/evals-with-memory.md

@@ -2,7 +2,7 @@
 
 # Evals with memory
 
-Agents that use memory in `thread` scope — including observational memory — require a thread ID at run time. When an eval invokes the agent without one, you'll see:
+Agents that use memory in `thread` scope, including observational memory, require a thread ID at run time. When an eval invokes the agent without one, you'll see:
 
 ```text
 ObservationalMemory (scope: 'thread') requires a threadId, but none was found in RequestContext or MessageList.
@@ -18,11 +18,11 @@ This page covers the three working patterns for running Mastra evals against mem
 | One independent thread per item, focused CI loop | [`runEvals` per item](#per-item-threads-with-runevals)                                    |
 | Per-item threads driven by a stored `Dataset`    | [`dataset.startExperiment` with an inline task](#dataset-experiments-with-an-inline-task) |
 
-Pre-seeding `RequestContext` with `MastraMemory` **isn't** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread` — `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
+Pre-seeding `RequestContext` with `MastraMemory` **isn't** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread`, `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
 
 ## Shared thread with `runEvals`
 
-`runEvals` accepts `targetOptions`, which is forwarded to `agent.generate()`. Passing `memory: { thread, resource }` runs every data item against the same thread — useful for testing recall across a multi-turn conversation.
+`runEvals` accepts `targetOptions`, which is forwarded to `agent.generate()`. Passing `memory: { thread, resource }` runs every data item against the same thread, useful for testing recall across a multi-turn conversation.
 
 ```typescript
 import { runEvals } from '@mastra/core/evals'
@@ -88,7 +88,7 @@ const average = scores.reduce((a, b) => a + b, 0) / scores.length
 
 ## Dataset experiments with an inline task
 
-`dataset.startExperiment({ target: agent })` **doesn't** forward a `memory` option to the agent — only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
+`dataset.startExperiment({ target: agent })` **doesn't** forward a `memory` option to the agent, only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
 
 ```typescript
 import { randomUUID } from 'node:crypto'

package/.docs/docs/evals/gates-and-verdicts.md

@@ -2,7 +2,7 @@
 
 # Gates and verdicts
 
-Gates and verdicts add severity semantics to `runEvals`. Gates are scorers that must score 1.0 — hard requirements that block a run. Thresholds are minimum acceptable scores on tracked metrics. The verdict summarizes the outcome as `passed`, `scored`, or `failed`.
+Gates and verdicts add severity semantics to `runEvals`. Gates are scorers that must score 1.0, hard requirements that block a run. Thresholds are minimum acceptable scores on tracked metrics. The verdict summarizes the outcome as `passed`, `scored`, or `failed`.
 
 ## When to use gates and verdicts
 
@@ -81,7 +81,7 @@ const result = await runEvals({
 })
 ```
 
-You must provide at least one scorer or gate — a run with neither throws an error.
+You must provide at least one scorer or gate, a run with neither throws an error.
 
 ## Thresholds
 
@@ -89,8 +89,8 @@ Wrap a scorer in `{ scorer, threshold }` to set pass/fail bounds. The threshold
 
 A `threshold` can be:
 
-- **A number** — implies minimum (score at or above passes): `{ scorer, threshold: 0.7 }`
-- **An object with `min` and/or `max`** — for range-based checks: `{ scorer, threshold: { max: 0.3 } }`
+- **A number**: implies minimum (score at or above passes): `{ scorer, threshold: 0.7 }`
+- **An object with `min` and/or `max`**: for range-based checks: `{ scorer, threshold: { max: 0.3 } }`
 
 Use `max` for scorers where a high score is bad (e.g., hallucination, toxicity). Use `{ min, max }` when the score should fall within a specific band.
 

package/.docs/docs/evals/multi-turn.md

@@ -37,9 +37,9 @@ Each turn runs `agent.generate()` with the same thread ID, so the agent sees the
 
 ## Memory is required for cross-turn recall
 
-Multi-turn recall depends on the agent having a **memory store configured**. The shared thread ID is what lets each turn see the earlier ones — but a thread only persists history when the agent has memory. If the agent has no memory configured, the turns still run sequentially and their outputs still accumulate for scoring, but the agent will not recall earlier turns (each input runs in isolation). `runEvals` logs a warning when you use `inputs` on an agent without memory.
+Multi-turn recall depends on the agent having a **memory store configured**. The shared thread ID is what lets each turn see the earlier ones, but a thread only persists history when the agent has memory. If the agent has no memory configured, the turns still run sequentially and their outputs still accumulate for scoring, but the agent won't recall earlier turns (each input runs in isolation). `runEvals` logs a warning when you use `inputs` on an agent without memory.
 
-`runEvals` manages the conversation identity for you: it generates the shared `threadId` and injects a `resourceId` (Mastra memory scopes messages by resource + thread, so both are required for recall to work). By default the resource is derived from the generated thread so each conversation is isolated. To pin a specific resource — for example to reuse an existing user's memory — pass `targetOptions.memory.resource`; `runEvals` still owns the thread, so you don't provide one:
+`runEvals` manages the conversation identity for you: it generates the shared `threadId` and injects a `resourceId` (Mastra memory scopes messages by resource + thread, so both are required for recall to work). By default the resource is derived from the generated thread so each conversation is isolated. To pin a specific resource, for example to reuse an existing user's memory, pass `targetOptions.memory.resource`; `runEvals` still owns the thread, so you don't provide one:
 
 ```typescript
 await runEvals({
@@ -61,18 +61,18 @@ When a data item has an `inputs` array, `runEvals`:
 3. Accumulates all output messages across turns
 4. Passes the full accumulated output to scorers for evaluation
 
-Scorers see the complete conversation output, not just the last turn.
+Scorers see the complete conversation output, including every turn.
 
 ## Scoring semantics
 
-Two details matter when writing scorers for multi-turn items:
+These details matter when writing scorers for multi-turn items:
 
-- **`run.output` is the accumulated output from every turn.** Output-based scorers — `checks.includes`, `checks.calledTool`, `checks.similarity`, and similar — evaluate the whole conversation. For example, `checks.calledTool('get_weather', { times: 2 })` counts calls across all turns.
+- **`run.output` is the accumulated output from every turn.** Output-based scorers: `checks.includes`, `checks.calledTool`, `checks.similarity`, and similar: evaluate the whole conversation. For example, `checks.calledTool('get_weather', { times: 2 })` counts calls across all turns.
 - **`run.input` is only the first turn's input.** Scorers that compare input against output (faithfulness, answer relevancy, and other input-relative LLM scorers) only see the first user message, not the full conversation. Prefer output-based checks for multi-turn, or build scorers that read the accumulated `run.output` directly.
 
 ## Per-turn assertions with `turns`
 
-The `inputs` form scores the **accumulated** output holistically — a single score over every turn's output. That can hide per-turn failures: an output-based check like `checks.includes('Brooklyn')` passes if _any_ turn mentions Brooklyn, even when the follow-up turn is broken.
+The `inputs` form scores the **accumulated** output as a whole, a single score over every turn's output. That can hide per-turn failures: an output-based check like `checks.includes('Brooklyn')` passes if _any_ turn mentions Brooklyn, even when the follow-up turn is broken.
 
 When you need to assert that a **specific turn** behaved correctly, use `turns` instead. Each turn is an object with its own `input` and optional `gates`/`scorers` that evaluate **only that turn's** input and output:
 
@@ -108,14 +108,14 @@ result.turnResults // per-turn gate/threshold/scorer outcomes
 
 Semantics:
 
-- A per-turn gate or scorer sees **only that turn's** `run.input` and `run.output` — never the accumulated conversation. This fixes both blind spots of `inputs`: the wrong turn can't satisfy a check, and `run.input` is correct for each turn.
-- Per-turn outcomes fold into the overall [verdict](https://mastra.ai/docs/evals/gates-and-verdicts): a failing turn gate makes the verdict `failed`; a missed turn threshold (with gates passing) makes it `scored`.
+- A per-turn gate or scorer sees **only that turn's** `run.input` and `run.output`: never the accumulated conversation. This fixes both blind spots of `inputs`: the wrong turn can't satisfy a check, and `run.input` is correct for each turn.
+- Per-turn outcomes fold into the [verdict](https://mastra.ai/docs/evals/gates-and-verdicts): a failing turn gate makes the verdict `failed`. A missed turn threshold (with gates passing) makes it `scored`.
 - `result.turnResults[i]` reports each turn's `gateResults`, `thresholdResults`, and `scores`, so a failure points at the exact turn. Across multiple conversations, turn results are averaged by turn index.
-- A turn with no `gates`/`scorers` just advances the conversation.
-- Top-level `scorers`/`gates` still run holistically over the accumulated output, so you can combine "this turn must call the tool" with "the overall answer mentions Brooklyn."
+- A turn with no `gates` or `scorers` advances the conversation.
+- Top-level `scorers`/`gates` still run as a whole over the accumulated output, so you can combine "this turn must call the tool" with "the answer mentions Brooklyn."
 - When the agent has storage configured, each per-turn scorer/gate result is persisted like top-level scores, so per-turn outcomes appear in your scores store. Each stored per-turn score is labeled with its turn index (`metadata.turnIndex`), shares the conversation's `threadId`, and links to that turn's own trace span.
 
-Use `inputs` when a single holistic score over the whole conversation is enough; use `turns` when correctness depends on individual turns. `turns` cannot be combined with `input` or `inputs` in the same data item.
+Use `inputs` when a single whole-conversation score over the whole conversation is enough. Use `turns` when correctness depends on individual turns. `turns` can't be combined with `input` or `inputs` in the same data item.
 
 ## Combining with gates and thresholds
 
@@ -156,7 +156,7 @@ const result = await runEvals({
 })
 ```
 
-Single-turn items use `input` as usual. Multi-turn items use `inputs` — `input` can be omitted entirely.
+Single-turn items use `input` as usual. Multi-turn items use `inputs`, `input` can be omitted entirely.
 
 ## Validation