@mastra/mcp-docs-server 1.2.24 → 1.2.25-alpha.1

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

@@ -442,7 +442,7 @@ Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/proc
 
 ### When to use response caching
 
-Reach for it when the same request shape repeats across users or sessions, for example prompt templates, suggested-prompt buttons, agentic search re-asks, or guardrail LLMs that classify the same input over and over. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
+Use caching when identical requests recur across users or sessions. Examples include suggested-prompt buttons and repeated searches, or guardrail LLMs that classify the same input. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
 
 ### Quickstart
 
@@ -546,7 +546,7 @@ The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is abo
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
-Multimodal prompts are included too. Image and file parts reach the key by value: the key includes a URL's full href, and a digest of the bytes for inline binary data (`Uint8Array`, `ArrayBuffer`). Requests that differ only in which image they reference therefore get different cache entries.
+Multimodal prompts are included too. For image and file parts, the key includes the full URL or a digest of the bytes for inline binary data (`Uint8Array`, `ArrayBuffer`). Requests that differ only in which image they reference therefore get different cache entries.
 
 #### Customize the cache key
 

package/.docs/docs/auth/fga.md

@@ -321,7 +321,7 @@ The actor signal is trusted input, so construct it server-side:
 - Establish tenant scope server-side. Built-in agent HTTP routes ignore a client-supplied `organizationId` in the request context, and the trusted-actor path requires an `organizationId` to be set.
 - Durable resume keeps its existing request-context recovery and merge behavior. This doesn't make a persisted actor trusted for a later workflow segment.
 - The tenant-scope check confirms that a trusted `organizationId` exists. It doesn't verify that `actor.agentId` belongs to that organization. When that relationship matters, verify it in `requireActor` using authoritative provider data.
-- Treat `actor.permissions` as an unverified claim. Resolve authoritative grants from a trusted source. A provider that enforces least privilege resolves the agent's authoritative permissions from a trusted source, for example a manifest or your FGA backend keyed by `agentId`, rather than trusting the inline values.
+- Treat `actor.permissions` as an unverified claim. To enforce least privilege, resolve the agent's permissions from a trusted source, such as a manifest or your FGA backend keyed by `agentId`. Don't trust the inline values.
 - Once a provider implements `requireActor`, errors from that method stop execution. Mastra doesn't fall back to organization-only authorization.
 
 ## Related

package/.docs/docs/channels.md

@@ -70,7 +70,7 @@ export const mastra = new Mastra({
 
 ## Webhook routes
 
-Platforms send channel activity to Mastra through webhooks. A webhook is an HTTP endpoint that the platform calls when something happens, such as a new message, a mention, or a user selecting "Approve" on an interactive tool approval card. This is how your agent receives a new message and starts processing it, plus responds in the same channel.
+Platforms send channel activity to Mastra through webhooks. A webhook is an HTTP endpoint that the platform calls when something happens, such as a new message, a mention, or a user selecting "Approve" on an interactive tool approval card. The webhook delivers the message to your agent for processing, and the agent responds in the same channel.
 
 Mastra registers a webhook route for each configured adapter and handles the request for you:
 

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

@@ -4,7 +4,7 @@
 
 # Custom scorers
 
-Mastra provides a unified `createScorer` factory that allows you to build custom evaluation logic using either JavaScript functions or LLM-based prompt objects for each step. This flexibility lets you choose the best approach for each part of your evaluation pipeline.
+Use `createScorer` to build custom evaluation logic. Each step can use a JavaScript function or an LLM-based prompt object, depending on what you're evaluating.
 
 ## The four-step pipeline
 
@@ -15,7 +15,7 @@ All scorers in Mastra follow a consistent four-step evaluation pipeline:
 3. **generateScore** (required): Convert analysis into a numerical score
 4. **generateReason** (optional): Generate human-readable explanations
 
-Each step can use either **functions** or **prompt objects** (LLM-based evaluation), giving you the flexibility to combine deterministic algorithms with AI judgment as needed.
+Combine **functions** and **prompt objects** within a scorer to use deterministic checks for some steps and LLM-based evaluation for others.
 
 ## Functions vs prompt objects
 

package/.docs/docs/evals/experiments.md

@@ -315,7 +315,7 @@ Teardown failures are logged rather than propagated. By the time `afterEach` run
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.
 
-Mocks live on the dataset item, so they version with the row and travel with the test case. Each mock declares a tool name, the arguments it expects, and the output to return:
+Mocks are stored and versioned with the dataset item. Each mock specifies the tool name and expected arguments, along with the output to return:
 
 ```typescript
 await dataset.addItem({
@@ -357,7 +357,7 @@ The item value takes precedence over the experiment value. A denied call fails w
 
 ### Matching and consumption
 
-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`.
+Arguments are matched strictly: object key order is ignored, but array order matters. Values aren't coerced to other types. 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.
 
@@ -390,7 +390,7 @@ While mock interception is active, the agent's tools execute sequentially so rep
 
 ### Diagnostics
 
-Each item result carries a `toolMockReport` describing what the run did with the item's mocks:
+Each item result includes a `toolMockReport` listing which mocks were used and which tool calls ran without a mock:
 
 ```typescript
 for (const item of summary.results) {

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

@@ -191,7 +191,7 @@ 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.
+- A per-turn gate or scorer receives **only that turn's** `run.input` and `run.output`, rather than the accumulated conversation. A different turn's output can't satisfy the check, and `run.input` contains the input for the turn being evaluated.
 - 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` or `scorers` advances the conversation.

package/.docs/docs/guides/streaming.md

@@ -108,7 +108,7 @@ Visit [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream) for
 
 ### Output from `Run.stream()`
 
-The event structure includes `runId` and `from` at the top level, making it easier to identify and track workflow runs without digging into the payload.
+Events include `runId` and `from` at the top level, so you can identify the workflow run without inspecting the payload.
 
 ```typescript
 {

package/.docs/docs/harness/agent-controller.md

@@ -22,7 +22,7 @@ Use the Agent Controller when your application needs:
 - Subagent orchestration to delegate focused subtasks with constrained tools
 - Persistent threads and selected thread settings across restarts, with isolated live state for each Session
 
-You could assemble all of this yourself on top of the [Agent class](https://mastra.ai/docs/agents/overview), which exposes the full agent loop, tools, and memory. The AgentController provides opinionated defaults for an ongoing session where the agent acts as a collaborator rather than a one-shot endpoint. Reach for the Agent class directly when you want full control or a request-response call. Reach for the AgentController when you want the collaborative-session model without building the runtime around it.
+You could assemble all of this yourself on top of the [Agent class](https://mastra.ai/docs/agents/overview), which exposes the full agent loop, tools, and memory. The AgentController provides opinionated defaults for an ongoing session where the agent acts as a collaborator rather than a one-shot endpoint. Use the Agent class directly for full control or request-response calls. Choose AgentController for ongoing sessions without building your own session runtime.
 
 ## Quickstart
 

package/.docs/docs/mastra-platform/database.md

@@ -97,7 +97,9 @@ Databases attached from project settings are project-scoped. Use the [CLI](#atta
 
 ## Connect from your code
 
-When a database is `ready`, the provider has finished provisioning and the platform has injected connection details as managed environment variables. Check status in **Project Settings → Database**, each attached database shows `provisioning` while setup runs in the background, then `ready` when you can connect. Open a `ready` database to view its environment variables and a copy-pasteable code snippet. Wire those variables into a Mastra storage adapter, with no manual configuration required.
+Check the database status in **Project Settings → Database**. An attached database shows `provisioning` while setup runs in the background. Once it's `ready`, the platform has injected its connection details as managed environment variables.
+
+Open a `ready` database to view those variables and a code snippet. Use the variables to configure a Mastra storage adapter, as shown below.
 
 ### Turso (LibSQL)
 

package/.docs/docs/memory/message-history.md

@@ -178,7 +178,7 @@ const agent = mastra.getAgentById('test-agent')
 const memory = await agent.getMemory()
 ```
 
-The `Memory` instance gives you access to functions for listing threads and recalling messages, plus cloning conversations, and more.
+Use the `Memory` instance to query stored threads and messages or clone a conversation.
 
 ## Querying
 

package/.docs/docs/memory/multi-user-threads.md

@@ -160,7 +160,7 @@ const memory = new Memory({
 
 OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, or `@mastra/oracledb`.
 
-> **Note:** If you switch the Observer to a weaker model and see facts collapse to a generic `User`, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to teach the Observer how to read the `<turn>` tag.
+> **Note:** If you switch the Observer to a less capable model and see facts attributed to a generic `User` instead of individual participants, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to explain how to interpret the `<turn>` tag.
 
 ### With working memory
 

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

@@ -718,7 +718,7 @@ Buffered observations also include continuation hints, a suggested next response
 
 When message production outpaces the Observer, the `blockAfter` safety threshold allows activation to overshoot the retention target instead of using fewer chunks. Activation still uses no more chunks than needed to reach the target, and the default settings remain unaffected. A synchronous observation runs when the `messageTokens` threshold is reached and buffered activation didn't happen. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
 
-Reflection works similarly, the Reflector runs in the background when observations reach a fraction of the reflection threshold.
+Reflection works similarly: the Reflector runs in the background when observations reach a fraction of the reflection threshold.
 
 ### Settings
 
@@ -809,6 +809,46 @@ const memory = new Memory({
 - `previousObserverTokens: 0` → omit previous observations completely.
 - `previousObserverTokens: false` → disable truncation and keep full previous observations.
 
+## Hooks
+
+OM exposes two kinds of config-level hooks on `observationalMemory.hooks`:
+
+- **Lifecycle hooks** (`onObservationStart`, `onObservationEnd`, `onReflectionStart`, `onReflectionEnd`) are telemetry callbacks. They receive `threadId`, `resourceId`, and `trigger`, and the end hooks also receive the model call's `usage`, `providerMetadata`, and any `error`. They never change what OM stores.
+- **Transform hooks** (`beforeObservation`, `afterObservation`, `beforeReflection`, `afterReflection`) intercept the data flowing through a cycle. Return `void` to pass the input through unchanged, or return a replacement to change what the Observer/Reflector sees or what gets persisted.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      hooks: {
+        // Drop or redact messages before the Observer sees them.
+        beforeObservation: ({ messages }) => ({
+          messages: messages.filter(m => !isSensitive(m)),
+        }),
+        // Rewrite observations before they are persisted.
+        afterObservation: ({ observations, threadId }) => ({
+          observations: redact(observations),
+        }),
+        // Rewrite the text the Reflector condenses, or its output.
+        beforeReflection: ({ observations }) => ({
+          observations: stripInternalNotes(observations),
+        }),
+        afterReflection: async ({ observations, resourceId }) => {
+          await syncToExternalStore(resourceId, observations)
+        },
+      },
+    },
+  },
+})
+```
+
+Transform hooks are always awaited, on every path (manual `observe()`/`reflect()`, turn-synchronous observation, and async buffering). If `beforeObservation` returns an empty `messages` array, the Observer model call is skipped and the filtered messages are still marked as observed. If a transform hook throws, the cycle fails before committing the transformed observation or reflection text. This doesn't roll back extractor callbacks or other side effects that have already run.
+
+`afterObservation` and `afterReflection` replace only the observation or reflection text. They don't recompute or redact the separate structured extractor results stored in thread metadata. Reflection extraction and its callbacks run before `afterReflection`, so rewriting the reflection doesn't rerun those callbacks. Use extractor configuration and callbacks to control structured values. Don't treat an after hook as a redaction boundary for all cycle data.
+
+Because hooks receive `threadId` and `resourceId`, you can also use them to update [working memory](https://mastra.ai/docs/memory/working-memory) via `memory.updateWorkingMemory()` during a cycle. These external updates aren't atomic with the OM text commit.
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.

package/.docs/docs/memory/overview.md

@@ -4,7 +4,7 @@
 
 # Memory
 
-Memory enables your agent to remember user messages and agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, plus produce better answers over time.
+Memory gives your agent access to earlier messages and tool results. The agent can use this context to answer follow-up questions and recall information from previous interactions.
 
 Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
 
@@ -153,7 +153,7 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 ## Observational Memory
 
-For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
+Long conversations can fill the context window with raw message history and reduce agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses background agents to compress older messages into observations. This reduces the context used by message history while retaining information for later turns.
 
 **For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
 
@@ -176,7 +176,7 @@ See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) f
 
 ## What the model sees
 
-Each memory feature is added to either the system messages or the conversation messages in the request sent to the model. The layers depend on the features you've enabled. Working memory and semantic recall only appear when configured. The same applies to Observational Memory, while message history is on by default. The diagram shows where each enabled layer is placed in the request. The list below describes what each layer contributes:
+Memory adds context to the system messages or conversation messages sent to the model. Message history is enabled by default. Other memory features contribute context only when configured. The diagram shows where each feature adds its context, and the list below explains what it contributes:
 
 ![Diagram showing how Mastra assembles the model context: system messages containing agent instructions, call-time system messages, working memory, cross-thread semantic recall, and Observational Memory, followed by conversation messages where message history and same-thread semantic recall interleave by timestamp, then call-time context messages, and finally the new user message](/img/memory/memory-context-window-light.svg)
 
@@ -202,7 +202,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 
 > **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
-The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved, the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/subagents) callback.
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved; the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/subagents) callback.
 
 > **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Different subagents under the same supervisor never share a resource ID through delegation.
 

package/.docs/docs/observability/tracing/overview.md

@@ -98,7 +98,7 @@ The `sampling` option allows you to control which traces are collected, helping
 
 ## Adding custom metadata
 
-Custom metadata allows you to attach additional context to your traces, making it easier to debug issues and understand system behavior in production.
+Add custom metadata to record application-specific context in your traces for debugging production issues.
 
 Metadata can include business logic and performance metrics. It can also carry user context or any other information that explains what happened during execution.
 
@@ -764,7 +764,7 @@ The trace ID is only available when tracing is enabled. If tracing is disabled o
 
 ## Integrating with external tracing systems
 
-When running Mastra agents or workflows within applications that have existing distributed tracing (OpenTelemetry, Datadog, etc.), you can connect Mastra traces to your parent trace context. This creates a unified view of your entire request flow, making it easier to understand how Mastra operations fit into the broader system.
+If your application already uses distributed tracing, such as OpenTelemetry or Datadog, you can connect Mastra traces to the parent trace context. This lets you follow a request through your application and its Mastra agent or workflow calls.
 
 ### Passing external trace IDs
 

package/.docs/docs/server/pubsub.md

@@ -4,7 +4,7 @@
 
 # PubSub
 
-Mastra uses a publish/subscribe (pub/sub) system as its internal event bus. Components publish events to topics, and other components subscribe to those topics to react. The backend you configure decides how far those events travel: within one process or across processes on one host, or alternatively across separate instances.
+Mastra uses a publish/subscribe (pub/sub) system as its internal event bus. Components publish events to topics, and other components subscribe to those topics to react. The backend determines whether events are delivered within a single process, between processes on one host, or across separate instances.
 
 Set the backend once on the `Mastra` instance for use throughout the system. The default is an in-process backend that requires no setup.
 

package/.docs/docs/studio/overview.md

@@ -67,7 +67,7 @@ Use [Agent Builder](https://agent-builder.mastra.ai) to create and manage fully
 
 Visualize your workflow as a graph and run it step by step with a custom input. During execution, the interface updates in real time to show the active step and the path taken.
 
-When running a workflow, you can also view detailed traces showing tool calls and raw JSON outputs, plus any errors that might have occurred along the way.
+Workflow traces show tool calls and raw JSON outputs, along with any execution errors.
 
 ### Processors
 

package/.docs/models/gateways/merge-gateway.md

@@ -4,7 +4,7 @@
 
 # ![Merge Gateway logo](https://models.dev/logos/merge-gateway.svg)Merge Gateway
 
-Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 180 models through Mastra's model router.
+Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 181 models through Mastra's model router.
 
 Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
 
@@ -95,6 +95,7 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemini-flash-lite-latest`                |
 | `google/gemma-4-26b-a4b-it`                      |
 | `google/gemma-4-31b-it`                          |
+| `meta/llama-3.1-70b-instruct`                    |
 | `meta/llama-3.1-8b-instruct`                     |
 | `meta/llama-3.3-70b-instruct`                    |
 | `meta/muse-spark-1.1`                            |

package/.docs/models/index.md

@@ -4,7 +4,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7118 models from 200 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7122 models from 200 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/edenai.md

@@ -4,7 +4,7 @@
 
 # ![Eden AI logo](https://models.dev/logos/edenai.svg)Eden AI
 
-Access 250 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
+Access 258 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
 
 Learn more in the [Eden AI documentation](https://docs.edenai.co).
 
@@ -19,7 +19,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "edenai/amazon/moonshot.kimi-k2-thinking"
+  model: "edenai/amazon/amazon.nova-lite-v1:0"
 });
 
 // Generate a response
@@ -38,6 +38,14 @@ for await (const chunk of stream) {
 
 | Model                                                                  | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ---------------------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `edenai/amazon/amazon.nova-lite-v1:0`                                  | 300K    |       |           |       |       |       | $0.06      | $0.24       |
+| `edenai/amazon/amazon.nova-lite-v1:0@us`                               | 300K    |       |           |       |       |       | $0.06      | $0.24       |
+| `edenai/amazon/amazon.nova-micro-v1:0`                                 | 128K    |       |           |       |       |       | $0.04      | $0.14       |
+| `edenai/amazon/amazon.nova-micro-v1:0@us`                              | 128K    |       |           |       |       |       | $0.04      | $0.14       |
+| `edenai/amazon/amazon.nova-pro-v1:0`                                   | 300K    |       |           |       |       |       | $0.80      | $3          |
+| `edenai/amazon/amazon.nova-pro-v1:0@us`                                | 300K    |       |           |       |       |       | $0.80      | $3          |
+| `edenai/amazon/mistral.pixtral-large-2502-v1:0`                        | 128K    |       |           |       |       |       | $2         | $6          |
+| `edenai/amazon/mistral.pixtral-large-2502-v1:0@us`                     | 128K    |       |           |       |       |       | $2         | $6          |
 | `edenai/amazon/moonshot.kimi-k2-thinking`                              | 128K    |       |           |       |       |       | $0.60      | $3          |
 | `edenai/amazon/moonshotai.kimi-k2.5`                                   | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `edenai/amazon/zai.glm-4.7-flash`                                      | 200K    |       |           |       |       |       | $0.07      | $0.40       |
@@ -208,8 +216,8 @@ for await (const chunk of stream) {
 | `edenai/perplexityai/sonar-deep-research`                              | 128K    |       |           |       |       |       | $2         | $8          |
 | `edenai/perplexityai/sonar-pro`                                        | 200K    |       |           |       |       |       | $3         | $15         |
 | `edenai/perplexityai/sonar-reasoning-pro`                              | 128K    |       |           |       |       |       | $2         | $8          |
-| `edenai/qwen/deepseek-v4-flash-0731`                                   | 1.0M    |       |           |       |       |       | $0.18      | $0.53       |
-| `edenai/qwen/deepseek-v4-pro-0813`                                     | 1.0M    |       |           |       |       |       | $0.58      | $2          |
+| `edenai/qwen/deepseek-v4-flash-0731`                                   | 1.0M    |       |           |       |       |       | $0.35      | $1          |
+| `edenai/qwen/deepseek-v4-pro-0813`                                     | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `edenai/qwen/qwen-max`                                                 | 33K     |       |           |       |       |       | $2         | $6          |
 | `edenai/qwen/qwen-vl-max`                                              | 131K    |       |           |       |       |       | $0.80      | $3          |
 | `edenai/qwen/qwen-vl-plus`                                             | 131K    |       |           |       |       |       | $0.21      | $0.63       |
@@ -301,7 +309,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.edenai.run/v3",
-    id: "edenai/amazon/moonshot.kimi-k2-thinking",
+    id: "edenai/amazon/amazon.nova-lite-v1:0",
     apiKey: process.env.EDENAI_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -320,7 +328,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "edenai/zai/glm-5v-turbo"
-      : "edenai/amazon/moonshot.kimi-k2-thinking";
+      : "edenai/amazon/amazon.nova-lite-v1:0";
   }
 });
 ```

package/.docs/models/providers/kilo.md

@@ -45,7 +45,7 @@ for await (const chunk of stream) {
 | `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.05      | $0.16       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
-| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $3         | $13         |
+| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~openai/gpt-latest`                                       | 1.1M    |       |           |       |       |       | $2         | $10         |
 | `kilo/~openai/gpt-mini-latest`                                  | 400K    |       |           |       |       |       | $0.75      | $5          |
 | `kilo/~x-ai/grok-latest`                                        | 500K    |       |           |       |       |       | $2         | $6          |
@@ -369,7 +369,7 @@ for await (const chunk of stream) {
 | `kilo/tencent/hy-mt2-1.8b`                                      | 8K      |       |           |       |       |       | $0.04      | $0.18       |
 | `kilo/tencent/hy-mt2-30b-a3b`                                   | 8K      |       |           |       |       |       | $0.07      | $0.29       |
 | `kilo/tencent/hy-mt2-7b`                                        | 8K      |       |           |       |       |       | $0.07      | $0.29       |
-| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.08      | $0.33       |
+| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.13      | $0.53       |
 | `kilo/tencent/hy3-preview`                                      | 262K    |       |           |       |       |       | $0.18      | $0.60       |
 | `kilo/tencent/hy4-preview`                                      | 1.0M    |       |           |       |       |       | $0.83      | $3          |
 | `kilo/thedrummer/cydonia-24b-v4.1`                              | 131K    |       |           |       |       |       | $0.30      | $0.50       |
@@ -394,7 +394,7 @@ for await (const chunk of stream) {
 | `kilo/z-ai/glm-4.5`                                             | 131K    |       |           |       |       |       | $0.60      | $2          |
 | `kilo/z-ai/glm-4.5-air`                                         | 131K    |       |           |       |       |       | $0.13      | $0.85       |
 | `kilo/z-ai/glm-4.5v`                                            | 66K     |       |           |       |       |       | $0.60      | $2          |
-| `kilo/z-ai/glm-4.6`                                             | 205K    |       |           |       |       |       | $0.55      | $2          |
+| `kilo/z-ai/glm-4.6`                                             | 198K    |       |           |       |       |       | $0.43      | $2          |
 | `kilo/z-ai/glm-4.6v`                                            | 131K    |       |           |       |       |       | $0.30      | $0.90       |
 | `kilo/z-ai/glm-4.7`                                             | 203K    |       |           |       |       |       | $0.40      | $2          |
 | `kilo/z-ai/glm-4.7-flash`                                       | 131K    |       |           |       |       |       | $0.06      | $0.40       |

package/.docs/models/providers/nano-gpt.md

@@ -4,7 +4,7 @@
 
 # ![NanoGPT logo](https://models.dev/logos/nano-gpt.svg)NanoGPT
 
-Access 589 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
+Access 584 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
 
 Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
 
@@ -82,11 +82,6 @@ for await (const chunk of stream) {
 | `nano-gpt/auto-model-basic`                                      | 1.0M    |       |           |       |       |       | $10        | $20         |
 | `nano-gpt/auto-model-premium`                                    | 1.0M    |       |           |       |       |       | $10        | $20         |
 | `nano-gpt/auto-model-standard`                                   | 1.0M    |       |           |       |       |       | $10        | $20         |
-| `nano-gpt/azure-gpt-4-turbo`                                     | 128K    |       |           |       |       |       | $10        | $30         |
-| `nano-gpt/azure-gpt-4o`                                          | 128K    |       |           |       |       |       | $3         | $10         |
-| `nano-gpt/azure-gpt-4o-mini`                                     | 128K    |       |           |       |       |       | $0.15      | $0.60       |
-| `nano-gpt/azure-o1`                                              | 200K    |       |           |       |       |       | $15        | $60         |
-| `nano-gpt/azure-o3-mini`                                         | 200K    |       |           |       |       |       | $1         | $4          |
 | `nano-gpt/baseten/Kimi-K2-Instruct-FP4`                          | 131K    |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/brave`                                                 | 8K      |       |           |       |       |       | $5         | $5          |
 | `nano-gpt/brave-pro`                                             | 8K      |       |           |       |       |       | $5         | $5          |

package/.docs/reference/agents/generate.md

@@ -166,7 +166,7 @@ const result = await agent.generate('message for agent')
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
-**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured. Also accepts firstChunkMs, which only applies to streaming calls and is the maximum time the model may take to emit its first content-bearing chunk (text, reasoning, tool call, file or source; stream-start and metadata chunks do not count). A firstChunkMs timeout fails with timeoutType: 'firstChunk', behaves like stepMs for fallback, and is reset for each provider retry attempt. Nested timeout keys are merged across call-time and per-model settings.
 
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 

package/.docs/reference/agents/network.md

@@ -102,7 +102,7 @@ await agent.network(`
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
-**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured. Also accepts firstChunkMs, which only applies to streaming calls and is the maximum time the model may take to emit its first content-bearing chunk (text, reasoning, tool call, file or source; stream-start and metadata chunks do not count). A firstChunkMs timeout fails with timeoutType: 'firstChunk', behaves like stepMs for fallback, and is reset for each provider retry attempt. Nested timeout keys are merged across call-time and per-model settings.
 
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 

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

@@ -6,7 +6,7 @@
 
 `buildBasePrompt()` builds the shared base system prompt for a coding agent: the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
 
-Product-specific strings are parameterized through `productName`, `coAuthorName`, and `coAuthorEmail`, so you can rebrand the prompt and commit trailer without forking it. They default to `"Mastra Code"` / `"noreply@mastra.ai"`, so existing callers keep identical output.
+Product-specific strings are parameterized through `productName`, `coAuthorName`, and `coAuthorEmail`, so you can rebrand the prompt and commit trailer without forking it. The co-author defaults to `"mastra-platform[bot]"` and `"284800079+mastra-platform[bot]@users.noreply.github.com"`.
 
 Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build runtime-defined instructions for the agent.
 
@@ -58,7 +58,7 @@ const prompt = buildBasePrompt({
 
 **mode** (`string`): Active agent mode (for example, "build" or "plan").
 
-**modelId** (`string`): Identifier of the active model, included in the commit Co-Authored-By line when provided.
+**modelId** (`string`): Identifier of the active model.
 
 **activePlan** (`{ title: string; plan: string; approvedAt: string } | null`): The currently approved plan, if any.
 
@@ -66,9 +66,9 @@ const prompt = buildBasePrompt({
 
 **productName** (`string`): Display name used in the prompt header. (Default: `Mastra Code`)
 
-**coAuthorName** (`string`): Name used in the commit Co-Authored-By line. (Default: `Mastra Code`)
+**coAuthorName** (`string`): Name used in the commit Co-Authored-By line. (Default: `mastra-platform[bot]`)
 
-**coAuthorEmail** (`string`): Email used in the commit Co-Authored-By line. (Default: `noreply@mastra.ai`)
+**coAuthorEmail** (`string`): Email used in the commit Co-Authored-By line. (Default: `284800079+mastra-platform[bot]@users.noreply.github.com`)
 
 ## Returns
 

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

@@ -85,7 +85,7 @@ Final score: `(covered_elements / total_input_elements) * scale`
 
 A completeness score between 0 and 1:
 
-- **1.0**: Thoroughly addresses all aspects of the query with detailed detail.
+- **1.0**: Addresses all aspects of the query in detail.
 - **0.7 to 0.9**: Covers most important aspects with good detail, minor gaps.
 - **0.4 to 0.6**: Addresses some key points but missing important aspects or lacking detail.
 - **0.1 to 0.3**: Only partially addresses the query with substantial gaps.

package/.docs/reference/evals/faithfulness.md

@@ -4,7 +4,7 @@
 
 # Faithfulness scorer
 
-The `createFaithfulnessScorer()` function evaluates how factually accurate an LLM's output is compared to the provided context. It extracts claims from the output and verifies them against the context, making it essential to measure RAG pipeline responses' reliability.
+The `createFaithfulnessScorer()` function evaluates how factually accurate an LLM's output is compared to the provided context. It extracts claims from the output and verifies them against the context. Use it to check whether a RAG response is supported by the retrieved information.
 
 ## Parameters
 

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

@@ -136,7 +136,7 @@ Each dimension receives an impact level with corresponding weights:
 - **Minimal (0.85)**: Slight phrasing changes but maintains correctness
 - **Moderate (0.6)**: Noticeable changes affecting quality but core info correct
 - **Significant (0.3)**: Major degradation in quality or accuracy
-- **Severe (0.1)**: Response substantially worse or completely derailed
+- **Severe (0.1)**: Response much worse than the baseline or unrelated to the original query
 
 ### Conservative Scoring
 

package/.docs/reference/evals/prompt-alignment.md

@@ -180,10 +180,8 @@ Final Score = Weighted Score × scale
 
 **Both Mode (`'both'`)** - Use when (default, recommended):
 
-- Comprehensive evaluation of AI agent performance
-- Balancing user satisfaction with system compliance
+- Evaluating whether responses satisfy user requests while following system instructions
 - Production monitoring where both user and system requirements matter
-- Holistic assessment of prompt-response alignment
 
 ## Common use cases
 
@@ -423,7 +421,7 @@ console.log(result)
 
 ### Excellent alignment output
 
-The output receives a high score because it perfectly addresses the intent and fulfills all requirements. It also uses the appropriate format.
+In this example, the response receives a high score because it provides the requested Python factorial function with error handling for negative numbers.
 
 ```typescript
 {

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

@@ -51,7 +51,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource'; instructions?: string }`): Let the agent look up the raw message history behind its observations. Observation groups keep durable pointers to the original messages, and a recall tool is registered so the agent can browse them. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. { instructions: '...' } appends application-specific recall guidance after Mastra's built-in retrieval instructions. (Default: `false`)
 
-**hooks** (`ObserveHooks`): Lifecycle hooks fired for every observation/reflection cycle — the manual observe()/reflect() APIs, turn-driven synchronous observation, and fire-and-forget async buffering. Callbacks receive threadId/resourceId/trigger call context ('manual' | 'turn-sync' | 'async-buffer'), and the end hooks (onObservationEnd/onReflectionEnd) additionally receive the OM model call's token usage and providerMetadata (where providers such as the AI Gateway report per-call cost), so apps can account for OM model spend without wrapping the observer/reflector models in middleware. Failed async-buffered cycles never throw; they report through the end hook's error field. Errors thrown by these hooks are caught and logged — they never fail the cycle.
+**hooks** (`ObserveHooks`): Lifecycle hooks fired for every observation/reflection cycle — the manual observe()/reflect() APIs, turn-driven synchronous observation, and fire-and-forget async buffering. Callbacks receive threadId/resourceId/trigger call context ('manual' | 'turn-sync' | 'async-buffer'), and the end hooks (onObservationEnd/onReflectionEnd) additionally receive the OM model call's token usage and providerMetadata (where providers such as the AI Gateway report per-call cost), so apps can account for OM model spend without wrapping the observer/reflector models in middleware. Config-level lifecycle hooks are non-blocking by default: their errors are logged without failing the cycle. With hookExecution: 'await', config-level lifecycle errors can reject observe() or reflect(). Per-call observe({ hooks }) lifecycle hooks are also awaited and can reject observe(). A failing awaited start hook skips the model call; an end-hook failure can reject the call after its work has completed. Async-buffered cycles always use non-blocking config-level lifecycle hooks, regardless of hookExecution. Their cycle failures are reported through onObservationEnd.error or onReflectionEnd.error, rather than thrown to the caller. ObserveHooks also accepts transform hooks that intercept and can replace cycle data: beforeObservation({ messages, ...context }) runs on the messages about to be observed (return { messages } to filter/redact; an empty array skips the Observer call), afterObservation({ observations, ...context }) runs on the Observer's output before it is persisted, beforeReflection({ observations, ...context }) runs on the text sent to the Reflector, and afterReflection({ observations, ...context }) runs on the Reflector's output before it is persisted. Transform hooks return void to pass data through unchanged and are always awaited on every path. A thrown error fails the cycle before committing its transformed observation or reflection text, but doesn't roll back extractor callbacks or other side effects that already ran. The after hooks replace only text, not the separate structured extractor results stored in thread metadata. Reflection extraction and its callbacks run before afterReflection; this hook neither recomputes extracted values nor reruns callbacks. After hooks aren't a redaction boundary for all cycle data.
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 

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

@@ -217,7 +217,7 @@ const run = await workflow.createRun();
 
 ### `setState()` is now async and the data passed is validated
 
-The `setState()` function is now async. The data passed is now validated against the `stateSchema` defined in the step. The state data validation also uses the `validateInputs` flag to determine whether to validate the state data or not. Also, when calling `setState()`, you can now pass only the state data being updated, instead of adding the previous state spread `(...state)`.
+The `setState()` function is now async and validates data against the step's `stateSchema` when `validateInputs` is enabled. Pass only the fields you want to update, without spreading the previous state (`...state`).
 
 To migrate, update the `setState()` function to be async.
 

package/.docs/reference/processors/regex-filter-processor.md

@@ -4,7 +4,7 @@
 
 # RegexFilterProcessor
 
-The `RegexFilterProcessor` applies zero-cost regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made. All detection is regex-based.
+The `RegexFilterProcessor` uses regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made.
 
 Supports built-in presets for common patterns (PII, secrets, URLs) and custom regex rules. Can be applied to input, output, or both phases.
 

package/.docs/reference/rag/vector-databases.md

@@ -650,7 +650,7 @@ Key metadata considerations:
 
 ## Deleting vectors
 
-When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it straightforward to remove all embeddings associated with a specific document.
+Use `deleteVectors` with a metadata filter to remove embeddings associated with a document. This is useful for cleaning up stale vectors after a document is deleted or updated.
 
 ### Delete by Metadata Filter
 

package/.docs/reference/streaming/agents/stream.md

@@ -160,7 +160,7 @@ const stream = await agent.stream('message for agent')
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
-**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured. Also accepts firstChunkMs, which only applies to streaming calls and is the maximum time the model may take to emit its first content-bearing chunk (text, reasoning, tool call, file or source; stream-start and metadata chunks do not count). A firstChunkMs timeout fails with timeoutType: 'firstChunk', behaves like stepMs for fallback, and is reset for each provider retry attempt. Nested timeout keys are merged across call-time and per-model settings.
 
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 
@@ -268,7 +268,7 @@ const fullText = await stream.text
 
 ### Limiting execution time
 
-Use `modelSettings.timeout` to bound how long a run may take. `totalMs` limits the entire run, including every loop iteration, tool call and retry. `stepMs` limits a single model call, covering both establishing the stream and consuming it.
+Use `modelSettings.timeout` to bound how long a run may take. `totalMs` limits the entire run, including every loop iteration, tool call and retry. `stepMs` limits a single model call, covering both establishing the stream and consuming it. `firstChunkMs` only applies to streaming calls and limits how long the model may take to emit its first content-bearing chunk.
 
 ```ts
 const stream = await agent.stream('Tell me a story', {
@@ -276,15 +276,19 @@ const stream = await agent.stream('Tell me a story', {
     timeout: {
       totalMs: 30000, // fail the run if it takes longer than 30s
       stepMs: 10000, // fail an individual model call after 10s
+      firstChunkMs: 3000, // fail a model call that produces no content within 3s
     },
   },
 })
 ```
 
-Exceeding either budget fails with a `MastraTimeoutError`, which carries a `timeoutType` of `'total'` or `'step'`. Each budget behaves differently when the agent is configured with fallback [`models`](https://mastra.ai/reference/agents/agent):
+Exceeding a budget fails with a `MastraTimeoutError`, which carries a `timeoutType` of `'total'`, `'step'` or `'firstChunk'`. Each budget behaves differently when the agent is configured with fallback [`models`](https://mastra.ai/reference/agents/agent):
 
 - A `totalMs` timeout ends the run immediately and doesn't try the next model, because it's a hard deadline for the run as a whole.
 - A `stepMs` timeout isn't retried against the same model, but does advance to the next model, which makes it a way to fail over from a slow provider.
+- A `firstChunkMs` timeout behaves like `stepMs`: it isn't retried against the same model, but does advance to the next model. Stream-start and metadata chunks don't satisfy the budget; only the first text, reasoning, tool call, file or source chunk does. Once content begins, only `stepMs` and `totalMs` remain active. Each provider retry attempt gets a fresh `firstChunkMs` budget.
+
+Nested `timeout` settings are merged per key across call-time and per-model `modelSettings`, so a per-model `stepMs` override keeps a call-time `firstChunkMs`.
 
 ### AI SDK v5+ Format
 

package/.docs/reference/tools/mcp-server.md

@@ -646,7 +646,7 @@ async executeTool(
 
 ### What are MCP Resources?
 
-Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions. They represent any kind of data that an MCP server wants to make available, such as:
+MCP resources expose server data that clients can read and use as context for LLM interactions. Examples include:
 
 - File contents
 - Database records

package/.docs/reference/workspace/sandbox.md

@@ -35,7 +35,7 @@ A sandbox constructed with a known `id` resolves that id on `start()`: reconnect
 
 Providers that predate the contract return `void`, which the base class treats as unknown.
 
-Provider implementations plug into the start lifecycle at one of three rungs; the best available wins, and the base class always owns coalescing, status management, the `onStart` hook, and mount processing:
+Providers implement the start lifecycle using one of the following approaches, listed in order of preference. The base class handles concurrent start calls and status management, as well as the `onStart` hook and mount processing:
 
 1. **Acquisition primitives**: implement protected `find()` (side-effect-free lookup by logical id, returning a provider-native handle or `undefined`), `connect(handle)` (wake/resume/adopt), and `create()` (provision fresh) without overriding `start()`. The base orchestrates find → connect → `{ outcome: 'connected' }`, else create → `{ outcome: 'created' }`. The outcome is derived structurally from which branch ran. Used by `E2BSandbox`, `DaytonaSandbox`, and `LocalSandbox`.
 2. **`start()` override returning `SandboxStartResult`**: for providers whose API is a fused get-or-create where decomposition would add round-trips (`PlatformSandbox`, `RailwaySandbox`).
@@ -47,7 +47,7 @@ The result is also forwarded to the `onStart` lifecycle hook as `{ sandbox, outc
 
 ### `onStart` (constructor option)
 
-`onStart` runs inside the start lifecycle, after the sandbox reaches `running` status and before pending mounts are processed. It fires on every start regardless of trigger, whether an explicit call, a lazy `ensureRunning()` from a command, or a revival after the provider replaced the VM. That makes it the seam for once-per-VM setup: branch on `outcome` and probe or run whatever the environment needs.
+`onStart` runs inside the start lifecycle, after the sandbox reaches `running` status and before pending mounts are processed. It fires on every start regardless of trigger, whether an explicit call, a lazy `ensureRunning()` from a command, or a revival after the provider replaced the VM. Use this hook for once-per-VM setup: check `outcome` to decide whether to run setup or check that it already completed.
 
 ```typescript
 new E2BSandbox({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.24",
+  "version": "1.2.25-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.65.0",
+    "@mastra/core": "1.66.0-alpha.0",
     "@mastra/mcp": "^1.17.3"
   },
   "devDependencies": {
@@ -45,7 +45,7 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
     "@internal/lint": "0.0.131",
-    "@mastra/core": "1.65.0",
+    "@mastra/core": "1.66.0-alpha.0",
     "@internal/types-builder": "0.0.106"
   },
   "homepage": "https://mastra.ai",