@mastra/mcp-docs-server 1.2.23-alpha.0 → 1.2.23-alpha.10

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

@@ -85,7 +85,7 @@ export const mastra = new Mastra({
 - `stop()` tears down the remote sandbox while preserving its recovery checkpoint when it has one.
 - `destroy()` also releases the recovery checkpoint associated with a caller-supplied recovery `id`.
 
-One statically configured `PlatformSandbox` is shared by every request and agent using that configuration. Requests and memory threads don't receive separate sandboxes automatically. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
+A statically configured `PlatformSandbox` is shared across every request and agent using that configuration rather than creating separate sandboxes for requests or memory threads. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
 
 When your agent needs another isolated environment, for example a per-task sandbox, a per-user tenant, or a background job that shouldn't touch shared shell state, construct another `PlatformSandbox`:
 

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

@@ -119,8 +119,8 @@ await agent.stream('Hello', {
 
 You can use this history in two ways:
 
-- **Automatic inclusion**: Mastra automatically fetches recent messages and includes them in the context window. By default, the last 10 messages keep agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
-- [**Manual querying**](#querying): For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
+- **Automatic inclusion**: Mastra automatically includes recent messages in the context window. The default of 10 messages keeps agents grounded in the conversation. Adjust it with `lastMessages` when needed.
+- [**Manual querying**](#querying): For more control, query threads and messages directly with `recall()`. Use the results to choose which memories enter the context window or to render conversation history in your UI.
 
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
@@ -230,7 +230,7 @@ const thread = await memory.getThreadById({ threadId: 'thread-123' })
 
 ### Messages
 
-Once you have a thread, use [`recall()`](https://mastra.ai/reference/memory/recall) to retrieve its messages. It supports pagination, date filtering, and [semantic search](https://mastra.ai/docs/memory/semantic-recall).
+Once you have a thread, use [`recall()`](https://mastra.ai/reference/memory/recall) to retrieve its messages. It supports pagination and [semantic search](https://mastra.ai/docs/memory/semantic-recall), with optional date filtering.
 
 Basic recall returns all messages from a thread:
 

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

@@ -31,7 +31,7 @@ export const agent = new Agent({
 
 **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.
 
-The following script creates a local LibSQL database, enables Observational Memory, and uses one resource and thread across two agent calls:
+The following script creates a local LibSQL database and enables Observational Memory before using one resource and thread across two agent calls:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -214,11 +214,11 @@ When message history tokens exceed a threshold (default: 30,000), the Observer c
 
 OM uses fast local token estimation for this thresholding work. Text is estimated with `tokenx`, while image parts use provider-aware heuristics so multimodal conversations still trigger observation at the right time. The same applies to image-like `file` parts when a transport normalizes an uploaded image as a file instead of an image part. For example, OpenAI image detail settings can materially change when OM decides to observe.
 
-The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
+The Observer can also see attachments in the history it reviews. For readability, OM keeps placeholders such as `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript while forwarding the actual attachments beside the text. When possible, image-like `file` parts become image inputs for the Observer. Other attachments remain file parts and use normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
 
 ### Extractors
 
-Use extractors when you want OM to persist specific values alongside observations. Built-in values such as **current task**, **suggested response**, and **thread title** use the same extraction pipeline as custom values.
+Use extractors when you want OM to persist specific values alongside observations. Built-in values use the same extraction pipeline as custom values. They include **current task** and **suggested response**, along with **thread title**.
 
 The following example extracts a compact user profile from observations:
 
@@ -380,7 +380,7 @@ new Agent({
 })
 ```
 
-You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` to let Mastra decide from the provider capabilities registry: attachments are forwarded when the Observer model supports multimodal input and dropped otherwise, falling back to `true` when no capability data is available for the model.
+You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` so Mastra consults the provider capabilities registry. It forwards attachments when the Observer model supports multimodal input and drops them otherwise. If capability data is unavailable for the model, the setting falls back to `true`.
 
 ```md
 Date: 2026-01-15
@@ -426,7 +426,7 @@ With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memor
 
 ### Retrieval mode
 
-Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
+Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. The agent can call a `recall` tool to recover source details compressed by the summary, including exact wording and tool output as well as chronology.
 
 #### Browsing only
 
@@ -716,23 +716,23 @@ When message tokens reach the `messageTokens` threshold, buffered chunks activat
 
 Buffered observations also include continuation hints, a suggested next response and the current task, so the main agent maintains conversational continuity after activation shrinks the context window.
 
-If the agent produces messages faster than the Observer can process them, the `blockAfter` safety threshold lets activation overshoot the retention target instead of activating fewer chunks. It never activates more chunks than are needed to reach that target, and with the default settings it changes nothing. 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.
+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.
 
 ### Settings
 
-| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                     |
-| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                 |
-| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, the threshold is 36k tokens (1.2 × 30k). Above it, activation may overshoot the retention target instead of activating fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
-| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.                                                                                         |
-| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                  |
-| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                  |
-| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                              |
-| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                            |
-| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                            |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                                |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                            |
+| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`. For example, `1.2` creates a threshold of 36k tokens (1.2 × 30k), above which activation may overshoot the retention target rather than use fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.                                                                                                    |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                             |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                             |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                                         |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                                       |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                                       |
 
 If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a specific cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
@@ -784,7 +784,7 @@ const memory = new Memory({
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
 
-> **Note:** Async buffering isn't supported with `scope: 'resource'`. It's automatically disabled in resource scope.
+> **Note:** Resource scope automatically disables async buffering.
 
 ## Observer Context Optimization
 

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

@@ -116,7 +116,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
    Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
 
-5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display memory details.
 
 ## Message history
 

package/.docs/docs/memory/semantic-recall.md

@@ -14,8 +14,6 @@ Semantic recall is RAG-based search that helps agents maintain context across lo
 
 It uses vector embeddings of messages for similarity search and integrates with vector stores, plus has configurable context windows around retrieved messages.
 
-![Diagram showing Mastra Memory semantic recall](/assets/images/semantic-recall-fd7b9336a6d0d18019216cb6d3dbe710.png)
-
 When it's enabled, new messages are used to query a vector DB for semantically similar messages.
 
 After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.

package/.docs/docs/memory/working-memory.md

@@ -275,7 +275,7 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 ## Choosing between template and schema
 
 - Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics**: the agent must provide the complete memory content on each update.
-- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. The `workingMemory.schema` field accepts any `PublicSchema`-compatible schema (including Zod v3, Zod v4, JSON Schema, or already-standard schemas). Schemas use **merge semantics**: the agent only provides fields to update, and existing fields are preserved.
+- Use a **schema** for structured, type-safe JSON data that supports validation and programmatic access. The `workingMemory.schema` field accepts any `PublicSchema`-compatible schema, such as Zod v3 or v4. JSON Schema and already-standard schemas are also supported. **Merge semantics** preserve existing fields when the agent provides only the fields to update.
 - Only one mode can be active at a time: setting both `template` and `schema` isn't supported.
 
 ## Example: Multi-step retention

package/.docs/docs/observability/feedback.md

@@ -155,7 +155,7 @@ The local runtime exposes the list route at `/api/observability/feedback` and an
 
 [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) forwards emitted feedback events to Mastra Platform automatically because the hosted query API doesn't provide a creation route.
 
-If your application adds feedback after an agent or workflow response using only its `traceId`, configure `MastraStorageExporter` alongside `MastraPlatformExporter`. The storage exporter keeps the trace available for `addFeedback()` to rehydrate, and the Platform exporter forwards the resulting feedback event. Exporting a trace to Platform doesn't make it available to the application's local storage.
+If your application adds feedback after an agent or workflow response using only its `traceId`, configure `MastraStorageExporter` alongside `MastraPlatformExporter`. The storage exporter keeps the trace available for `addFeedback()` to rehydrate, while the Platform exporter forwards the resulting feedback event without adding the trace to the application's local storage.
 
 See [Observability on Mastra Platform](https://mastra.ai/docs/mastra-platform/observability) for the combined exporter configuration.
 
@@ -166,7 +166,7 @@ Feedback flows through the observability event bus, so exporters that support fe
 ## Related
 
 - [Observability overview](https://mastra.ai/docs/observability/overview)
-- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Traces usage](https://mastra.ai/docs/observability/tracing/overview)
 - [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
 - [Client SDK observability reference](https://mastra.ai/reference/client-js/observability)
 - [Feedback reference](https://mastra.ai/reference/observability/feedback)

package/.docs/docs/observability/integrations/exporters/mastra-storage.md

@@ -248,7 +248,7 @@ new MastraStorageExporter({
 
 ## Related
 
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Traces usage](https://mastra.ai/docs/observability/tracing/overview)
 - [MastraPlatformExporter](https://mastra.ai/docs/mastra-platform/observability)
 - [Composite Storage](https://mastra.ai/reference/storage/composite): Combine multiple storage providers
 - [Storage Configuration](https://mastra.ai/docs/storage)

package/.docs/docs/observability/logging.md

@@ -78,7 +78,7 @@ export const mastra = new Mastra({
 
 ### Custom loggers
 
-Custom `IMastraLogger` implementations keep working: Mastra falls back to a dual-write wrapper that forwards log calls to observability. This fallback doesn't add `trace_id`/`span_id` to the logger's native output and is deprecated. To get trace-correlated output, implement the `__attachObservability()` adapter hook from `@mastra/core/logger`:
+Custom `IMastraLogger` implementations keep working: Mastra uses a deprecated dual-write fallback that forwards log calls to observability without adding `trace_id` or `span_id` to the logger's native output. To get trace-correlated output, implement the `__attachObservability()` adapter hook from `@mastra/core/logger`:
 
 ```typescript
 import { MastraLogger, buildLogRecordData } from '@mastra/core/logger'

package/.docs/docs/observability/metrics/overview.md

@@ -104,5 +104,5 @@ In production, always include a timestamp range in metric queries. Time bounds l
 ## Related
 
 - [Observability overview](https://mastra.ai/docs/observability/overview)
-- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Traces usage](https://mastra.ai/docs/observability/tracing/overview)
 - [MastraStorageExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)

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

@@ -4,14 +4,16 @@
 
 # Observability
 
-Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. Agent behavior depends on model responses, prompts, tools, memory, and workflow state, so observability helps you inspect runtime decisions from day one. It captures complementary signals that work together to help you understand what your application is doing and why.
+Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. Agent behavior depends on model responses, prompts, tools, memory, and workflow state, so observability helps you inspect runtime decisions from day one.
 
-- [**Configuration**](#configuration): Configure observability once for traces, logs, metrics, and feedback.
-- [**Storage**](#storage): Choose storage backends for persisted traces, logs, metrics aggregation, and feedback queries.
-- [**Tracing**](https://mastra.ai/docs/observability/tracing/overview): Records every operation as a hierarchical timeline of spans, capturing inputs, outputs, token usage, and timing.
-- [**Logging**](https://mastra.ai/docs/observability/logging): Forwards structured log entries from your application and Mastra internals to observability storage, correlated to traces automatically.
-- [**Metrics**](https://mastra.ai/docs/observability/metrics/overview): Extracts trace usage and cost data. No additional instrumentation is required.
-- [**Feedback**](https://mastra.ai/docs/observability/feedback): Stores ratings, comments, corrections, and other review signals linked to traces and spans.
+Start with the trace-correlated pages:
+
+- [**Usage**](https://mastra.ai/docs/observability/tracing/overview): Inspect the span hierarchy, inputs, outputs, token usage, timing, and trace context for an execution.
+- [**Logging**](https://mastra.ai/docs/observability/logging): Forward structured log entries from your application and Mastra internals, correlated to traces automatically.
+- [**Feedback**](https://mastra.ai/docs/observability/feedback): Store ratings, comments, corrections, and other review signals linked to traces and spans.
+- [**Storage**](#storage): Choose backends for persisted traces, logs, metrics aggregation, and feedback queries.
+
+Use [**Metrics**](https://mastra.ai/docs/observability/metrics/overview) to analyze aggregate usage, performance, and cost data derived from spans. No additional instrumentation is required. Use [**Configuration**](#configuration) to enable the signals and exporters your application needs.
 
 ## When to use observability
 
@@ -23,15 +25,15 @@ Mastra's observability system gives you visibility into every agent run, workflo
 
 ## How the pieces fit together
 
-Tracing is the foundation. When observability is configured, every agent run, workflow execution, tool call, and model interaction produces a [span](https://opentelemetry.io/docs/concepts/signals/traces/#spans). Spans are organized into traces that show the full request lifecycle as a hierarchical timeline.
+When observability is configured, every agent run, workflow execution, tool call, and model interaction produces a [span](https://opentelemetry.io/docs/concepts/signals/traces/#spans). Mastra organizes related spans into traces that show the full request lifecycle as a hierarchical timeline.
 
-Metrics are derived from traces automatically. When a span ends, Mastra extracts duration, token counts, and cost estimates without any extra code. These metrics power the dashboards in [Studio](https://mastra.ai/docs/studio/observability).
+When a span ends, Mastra extracts duration, token counts, and cost estimates without any extra code. These metrics power the aggregate dashboards in [Studio](https://mastra.ai/docs/studio/observability).
 
-Logs are correlated to traces automatically. Every `logger.info()`, `logger.warn()`, or `logger.error()` call within a traced context is tagged with the current trace and span IDs. You can move through from a log entry directly to the trace that produced it.
+Every `logger.info()`, `logger.warn()`, or `logger.error()` call within a traced context is tagged with the current trace and span IDs. You can move from a log entry directly to the trace that produced it.
 
 Feedback records human review signals such as ratings, comments, and corrections. Feedback can be linked to traces and spans, then queried with the same observability store used for metrics.
 
-These signals share correlation IDs such as trace ID, span ID, entity type, and entity name. You can use them to move from a metric spike to its traces, logs, and related feedback.
+These records share correlation fields such as trace ID, span ID, entity type, and entity name. You can use them to move from a metric spike to its traces, logs, and related feedback.
 
 ## Quickstart
 

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

@@ -2,7 +2,7 @@
 
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Traces
+# Usage
 
 Tracing is the observability signal that records how a request moves through agents, workflows, tools, and model calls. Mastra represents each operation as a span and groups related spans into a trace so you can inspect the full execution path.
 
@@ -144,7 +144,7 @@ export const mastra = new Mastra({
 })
 ```
 
-If `environment` isn't set, Mastra falls back to `process.env.NODE_ENV`. If neither is set, the field is left undefined rather than guessed.
+If `environment` isn't set, runs started through `mastra dev` resolve to `development` (even though the dev server itself runs with `NODE_ENV=production`); otherwise Mastra falls back to `process.env.NODE_ENV`. If none of these are set, the field is left undefined rather than guessed.
 
 Per-call `tracingOptions.metadata.environment` always takes precedence, so individual calls can override the value when needed.
 
@@ -660,8 +660,8 @@ export const mastra = new Mastra({
       default: {
         serviceName: 'my-service',
         serializationOptions: {
-          maxStringLength: 2048, // Maximum length for string values (default: 1024)
-          maxDepth: 10, // Maximum depth for nested objects (default: 6)
+          maxStringLength: 2048, // Maximum length for string values (default: 131072)
+          maxDepth: 10, // Maximum depth for nested objects (default: 8)
           maxArrayLength: 100, // Maximum number of items in arrays (default: 50)
           maxObjectKeys: 75, // Maximum number of keys in objects (default: 50)
         },
@@ -674,12 +674,12 @@ export const mastra = new Mastra({
 
 ### Available options
 
-| Option            | Default | Description                                                      |
-| ----------------- | ------- | ---------------------------------------------------------------- |
-| `maxStringLength` | 1024    | Maximum length for string values. Longer strings are truncated.  |
-| `maxDepth`        | 6       | Maximum depth for nested objects. Deeper levels are omitted.     |
-| `maxArrayLength`  | 50      | Maximum number of items in arrays. Additional items are omitted. |
-| `maxObjectKeys`   | 50      | Maximum number of keys in objects. Additional keys are omitted.  |
+| Option            | Default         | Description                                                      |
+| ----------------- | --------------- | ---------------------------------------------------------------- |
+| `maxStringLength` | 131072 (128 KB) | Maximum length for string values. Longer strings are truncated.  |
+| `maxDepth`        | 8               | Maximum depth for nested objects. Deeper levels are omitted.     |
+| `maxArrayLength`  | 50              | Maximum number of items in arrays. Additional items are omitted. |
+| `maxObjectKeys`   | 50              | Maximum number of keys in objects. Additional keys are omitted.  |
 
 ### Use cases
 
@@ -687,9 +687,9 @@ export const mastra = new Mastra({
 
 ```ts
 serializationOptions: {
-  maxStringLength: 8192,  // Capture longer text content
-  maxDepth: 12,           // Handle deeply nested JSON responses
-  maxArrayLength: 200,    // Keep more items from large lists
+  maxStringLength: 262144, // Capture longer text content (256 KB)
+  maxDepth: 12,            // Handle deeply nested JSON responses
+  maxArrayLength: 200,     // Keep more items from large lists
 }
 ```
 

package/.docs/docs/sandbox/lsp.md

@@ -149,7 +149,7 @@ lsp: {
 },
 ```
 
-`binaryOverrides` maps a built-in server ID to its full startup command. `searchPaths` adds package roots whose `node_modules` may contain binaries or required modules. You can also set `packageRunner`, such as `pnpm dlx`, as a last-resort fallback. Package-runner fallback is disabled by default because it may install software or hang in some project layouts.
+`binaryOverrides` maps a built-in server ID to its full startup command. `searchPaths` adds package roots whose `node_modules` may contain required modules or binaries. As a last-resort fallback, you can set a `packageRunner` such as `pnpm dlx`. Package-runner fallback is disabled by default because it may install software or hang in some project layouts.
 
 `diagnosticTimeout` controls how long the direct `getDiagnostics()` and `getDiagnosticsMulti()` APIs wait for diagnostics. The agent inspection tool currently waits up to five seconds.
 

package/.docs/docs/sandbox/overview.md

@@ -264,7 +264,7 @@ The example mounts the filesystem inside the resolver because static `mounts` ca
 
 With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it.
 
-With a [resolver-backed sandbox](#sandboxes-per-user-or-thread), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
+Because a [resolver-backed sandbox](#sandboxes-per-user-or-thread) isn't known until request time, Mastra initially exposes every sandbox tool. Calling one unsupported by the resolved backend fails with `SandboxFeatureNotSupportedError`.
 
 ## Background processes
 

package/.docs/docs/server/mastra-client.md

@@ -305,7 +305,7 @@ export const colorAgent = new Agent({
 
 ## Use MastraClient on the server
 
-You can also use `MastraClient` in server-side environments such as API routes, serverless functions, or actions. The usage remains the same, but you may need to recreate the response for your client:
+Server-side API routes and serverless functions, including actions, can also use `MastraClient`. The usage is unchanged, although you may need to recreate the response for your client:
 
 ```typescript
 export async function action() {

package/.docs/docs/server/overview.md

@@ -66,7 +66,7 @@ Mastra exposes OpenAI-compatible Responses and Conversations routes that let you
 
 These APIs are currently experimental.
 
-Use `agent_id` to select the Mastra agent that should handle the request. Initial requests target an agent directly, and stored follow-up turns can continue with `previous_response_id`. You can also pass `model` to override the agent's configured model for a single request. If you omit `model`, Mastra uses the model already configured on the agent.
+Use `agent_id` to select the Mastra agent that should handle the request. Initial requests target an agent directly. Stored follow-up turns can continue through `previous_response_id`. Pass `model` to override the configured model for one request, or omit it to use the agent's existing model.
 
 The Responses routes support streaming, function calling (tools), stored continuations with `previous_response_id`, conversation threads through `conversation_id`, provider-specific passthrough with `providerOptions`, and JSON output through `text.format`.
 

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

@@ -6,7 +6,7 @@
 
 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.
 
-You set the backend once on the `Mastra` instance, and the rest of the system uses it without changes. By default, Mastra uses an in-process backend that needs no setup.
+Set the backend once on the `Mastra` instance for use throughout the system. The default is an in-process backend that requires no setup.
 
 ## How Mastra uses PubSub
 

package/.docs/docs/server/request-context.md

@@ -152,7 +152,7 @@ You can also use `requestContext` with other options like `agents`, `workflows`,
 
 ### Dynamic instructions
 
-Agent instructions can be provided as an async function, enabling you to resolve prompts at runtime. Combined with `requestContext`, this enables patterns like:
+Provide agent instructions through an async function to resolve prompts at runtime. Together with `requestContext`, this supports patterns like:
 
 - **Personalization**: Tailor instructions based on user attributes, preferences, or tier
 - **Localization**: Adjust tone, language, or behavior based on locale
@@ -270,7 +270,7 @@ auth: {
 }
 ```
 
-When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies, the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies. The server-derived value is used instead and always takes precedence over a client-provided value. If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
 
 You can also set these keys manually in middleware:
 

package/.docs/docs/server/server-adapters.md

@@ -337,7 +337,7 @@ bun add @mastra/nestjs@latest
 
 ## Configuration
 
-Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. You can continue adding your own routes as normal, either before or after `init()`, and they’ll run alongside Mastra’s endpoints.
+Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. Continue adding your own routes either before or after `init()`. They run alongside Mastra’s endpoints.
 
 **Elysia**:
 

package/.docs/docs/skills.md

@@ -6,7 +6,7 @@
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
 
-You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/sandbox/skills). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
+Attach skills directly through an agent's `skills` config, or configure them on a [workspace](https://mastra.ai/docs/sandbox/skills). Agent-level skills belong to one agent and can be defined in code without a workspace, while workspace skills are discovered from the filesystem and shared by every agent using that workspace. This page explains how to define and load agent-level skills with per-request resolution.
 
 ## When to use agent-level skills
 

package/.docs/docs/studio/deployment.md

@@ -51,7 +51,7 @@ Run the `mastra studio` command:
 mastra studio
 ```
 
-Open [localhost:3000](http://localhost:3000) in your browser to see the Studio UI. By default, it will attempt to connect to a Mastra server running at `http://localhost:4111`. If it doesn't find one there, you'll see a form where you can enter your Mastra instance URL and API prefix.
+Open [localhost:3000](http://localhost:3000) in your browser to see the Studio UI. By default, it connects to a Mastra server at `http://localhost:4111`; when no server is available, the UI displays a form for entering your Mastra instance URL and API prefix.
 
 The command uses Node's built-in `http` module and [`serve-handler`](https://www.npmjs.com/package/serve-handler) to serve the static files.
 

package/.docs/docs/studio/editor.md

@@ -77,7 +77,7 @@ An instruction block can include values from the current request. For example, `
 
 ### Prompt blocks
 
-A prompt block is a saved piece of instruction text that can be used by more than one agent. Create one under **Prompts**, publish it, then open an agent's **Instructions** section and select **Add block**.
+A prompt block is a saved piece of instruction text that can be used by more than one agent. Create and publish one under **Prompts**. Then open an agent's **Instructions** section and select **Add block**.
 
 For example, agents for support, returns, and order status may all need the same refund policy. Save the policy as a prompt block and add it to each agent. When the policy changes, update and publish the block once instead of editing three agents.
 

package/.docs/docs/studio/observability.md

@@ -102,7 +102,7 @@ Above the trace list, open **Columns** to show or hide input, entity, duration,
 
 Token and estimated cost columns require an observability store that supports metrics. These columns stay hidden in the **Branches** view because several branch rows can belong to the same trace.
 
-Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
+Tracing filters out low-level framework details so your traces stay focused and readable. Visit [Traces usage](https://mastra.ai/docs/observability/tracing/overview) for more details.
 
 To export a trace, select **Download trace JSON** in the trace panel header. This saves the entire trace as a `trace-<id>.json` file, with every span and its full input, output, metadata, and attributes. Use it to share a trace or attach it to a bug report, or alternatively build an evaluation dataset offline.
 
@@ -116,6 +116,6 @@ Log forwarding is enabled by default when you configure observability. See [logg
 
 - [Observability overview](https://mastra.ai/docs/observability/overview)
 - [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
-- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Traces usage](https://mastra.ai/docs/observability/tracing/overview)
 - [Logging](https://mastra.ai/docs/observability/logging)
 - [Mastra platform observability](https://mastra.ai/docs/mastra-platform/observability)

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

@@ -41,7 +41,7 @@ Once the server is running, you can:
 - Open the Studio UI at [`localhost:4111`](http://localhost:4111/) to interact with your agents, workflows, and tools.
 - Visit [`localhost:4111/swagger-ui`](http://localhost:4111/swagger-ui) to discover and interact with the underlying REST API.
 
-While Studio is running, you can edit your [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), and other parts of your Mastra application in real time.
+Studio lets you edit your [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), and other parts of your Mastra application in real time.
 
 ## Deploy Studio
 

package/.docs/docs/subagents.md

@@ -138,7 +138,7 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
 - Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
 
-Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text. The parent model reads this as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
+Set `resultText` when the subagent's own result would give the parent a misleading signal. For example, empty text from a subagent stopped on a tool-calls step looks like a successful but empty delegation to the parent model. Unlike `feedback` on the next turn, `resultText` affects the parent's reasoning immediately.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -196,7 +196,7 @@ await parentAgent.generate('Research AI trends', { maxSteps: 10, requestContext
 const hookErrors = requestContext.get('__mastra_delegationHookErrors') ?? []
 ```
 
-When `hookErrorStrategy` is `'throw'`, a throwing `onDelegationStart` blocks the subagent from running at all, and a throwing `messageFilter` or `onDelegationComplete` surfaces to the parent as a failed tool call. If `onDelegationComplete` throws while handling a failed delegation, the original delegation error is still what surfaces, and the hook is never re-invoked for its own failure.
+When `hookErrorStrategy` is `'throw'`, a throwing `onDelegationStart` blocks the subagent from running at all, and a throwing `messageFilter` or `onDelegationComplete` surfaces to the parent as a failed tool call. If `onDelegationComplete` throws while handling a failed delegation, the original delegation error remains the surfaced error. The hook isn't invoked again for its own failure.
 
 ## Message filtering
 

package/.docs/docs/workflows/agents-and-tools.md

@@ -41,8 +41,6 @@ const step1 = createStep({
 
 Compose an agent as a step using `createStep()` when you don't need to modify the agent call. Use `.map()` to transform the previous step's output into a `prompt` the agent can use.
 
-![Agent as step](/assets/images/workflows-agent-tools-agent-step-b2f5be22552ce514f7f8cd785ffc5604.jpg)
-
 ```typescript
 import { testAgent } from '../agents/test-agent'
 const step1 = createStep(testAgent)
@@ -155,8 +153,6 @@ const step2 = createStep({
 
 Compose a tool as a step using `createStep()` when the previous step's output matches the tool's input context. You can use `.map()` to transform the previous step's output if they don't.
 
-![Tool as step](/assets/images/workflows-agent-tools-tool-step-cfd56227ce83c2d03a8c8d0496faeeef.jpg)
-
 ```typescript
 import { testTool } from '../tools/test-tool'
 

package/.docs/docs/workflows/control-flow.md

@@ -4,7 +4,7 @@
 
 # Control flow
 
-Workflows run a sequence of predefined tasks, and you can control how that flow is executed. Tasks are divided into **steps**, which can be executed in different ways depending on your requirements. They can run sequentially or in parallel, or alternatively follow different paths based on conditions.
+Workflows give you control over predefined tasks by dividing each task into **steps**. Those steps can run sequentially or in parallel, and they can follow conditional paths.
 
 Each step connects to the next in the workflow through defined schemas that keep data controlled and consistent.
 
@@ -212,8 +212,6 @@ Visit [Choosing the right pattern](#choosing-the-right-pattern) to understand wh
 
 Use `.branch()` to choose which step to run based on a condition. All steps in a branch need the same `inputSchema` and `outputSchema` because branching requires consistent schemas so workflows can follow different paths.
 
-![Conditional branching with .branch()](/assets/images/workflows-control-flow-branch-1913ef107ba0198d73aa3c0a65145b7a.jpg)
-
 ```typescript
 const step1 = createStep({...})
 

package/.docs/docs/workflows/overview.md

@@ -4,7 +4,7 @@
 
 # Workflows
 
-Workflows let you define complex sequences of tasks using clear, structured steps rather than relying on the reasoning of a single agent. They give you full control over how tasks are broken down and how data moves between them, plus what gets executed when. Workflows run using the built-in execution engine by default, or can be deployed to [workflow runners](https://mastra.ai/docs/deployment/workflow-runners) like Inngest for managed infrastructure.
+Workflows let you define complex task sequences with clear, structured steps instead of relying on one agent to reason through the entire process. You control the task breakdown along with the flow and timing of data. Workflows use the built-in execution engine by default, while managed infrastructure is available through [workflow runners](https://mastra.ai/docs/deployment/workflow-runners) such as Inngest.
 
 **For AI agents:** Run `npx mastra api workflow run start test-workflow '{"inputData":{"message":"Hello, world!"}}'` to start this workflow directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api workflow run start --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
 

package/.docs/docs/workflows/scheduled-workflows.md

@@ -44,7 +44,7 @@ A separate "register schedule" call won't happen. The scheduler reads `schedule`
 
 A workflow that declares `schedule` is auto-promoted to the **evented execution engine**. The public API (`workflow.start()`, `workflow.startAsync()`, `streamLegacy()`, `resume()`) is unchanged, `EventedWorkflow extends Workflow` and overrides each method with matching signatures. From your code, scheduled fires and manual runs are indistinguishable.
 
-The promotion has one practical implication: evented runs require a storage adapter that supports concurrent updates, for example `@mastra/libsql`. If your adapter doesn't, `createRun()` throws a clear error pointing at the `schedule` field. Switch adapters or remove the schedule.
+The promotion means evented runs require a storage adapter with concurrent-update support, such as `@mastra/libsql`; otherwise, `createRun()` throws a clear error that points to the `schedule` field. Switch adapters or remove the schedule.
 
 ## Single schedule
 

package/.docs/docs/workflows/suspend-and-resume.md

@@ -4,7 +4,7 @@
 
 # Suspend and resume
 
-Workflows can be paused at any step to collect additional data or wait for API callbacks. Pauses can also throttle costly operations or request [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) input. When a workflow is suspended, its current execution state is saved as a snapshot. You can later resume the workflow from a [specific step ID](https://mastra.ai/docs/workflows/snapshots), restoring the exact state captured in that snapshot. [Snapshots](https://mastra.ai/docs/workflows/snapshots) are stored in your configured storage provider and persist across deployments and application restarts.
+Pause a workflow at any step to collect additional data, wait for an API callback, throttle a costly operation, or request [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) input. Suspension saves the current execution state as a snapshot. Later, resume from a [specific step ID](https://mastra.ai/docs/workflows/snapshots) to restore the exact captured state. [Snapshots](https://mastra.ai/docs/workflows/snapshots) are stored in your configured storage provider and persist across deployments and application restarts.
 
 ## Pausing a workflow with `suspend()`
 
@@ -98,7 +98,7 @@ const stream = run.resume({
 })
 ```
 
-You can call `resume()` from anywhere in your application, including HTTP endpoints, event handlers, in response to [human input](https://mastra.ai/docs/workflows/human-in-the-loop), or timers.
+You can call `resume()` from anywhere in your application, such as an HTTP endpoint or event handler. Timers and code responding to [human input](https://mastra.ai/docs/workflows/human-in-the-loop) can also resume a workflow.
 
 ```typescript
 const midnight = new Date()