@mastra/mcp-docs-server 1.2.16-alpha.1 → 1.2.16-alpha.4

package/.docs/reference/file-based-agents/config.md

@@ -101,7 +101,7 @@ Missing `instructions.md`, `instructions.ts`, and `config.instructions` fails th
 
 ## Discovery lifecycle
 
-File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/`, imports TypeScript and JavaScript modules, reads markdown instructions and skills, copies workspace seed files, and registers the assembled primitives with your Mastra app.
+File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/` and imports TypeScript and JavaScript modules. It also reads markdown instructions and skills. The bundler then copies workspace seed files and registers the assembled primitives with your Mastra app.
 
 After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent.
 

package/.docs/reference/file-based-agents/skills.md

@@ -22,11 +22,11 @@ Always report temperatures in Celsius and Fahrenheit. Include the user's preferr
 
 ## Skills vs tools vs instructions
 
-| Need                                                 | Use                                                                             | Why                                                                  |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Always-on identity, tone, or rules                   | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The model should see the guidance every turn.                        |
-| Callable action with inputs and outputs              | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | The model needs to execute code, call APIs, or perform side effects. |
-| Detailed reference or procedure loaded when relevant | `skills/`                                                                       | The model only needs the full guidance for specific tasks.           |
+| Need                                                 | Use                                                                             | Why                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Always-on identity, tone, or rules                   | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The model should see the guidance every turn.                                                 |
+| Callable action with inputs and outputs              | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | The model needs to execute code or call APIs, including operations that perform side effects. |
+| Detailed reference or procedure loaded when relevant | `skills/`                                                                       | The model only needs the full guidance for specific tasks.                                    |
 
 ## Skill formats
 

package/.docs/reference/file-based-agents/workspace.md

@@ -15,7 +15,7 @@ Without `workspace.ts`, a file-based agent gets a default [`Workspace`](https://
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) rooted at the agent's bundled workspace directory.
 - [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) with the same working directory.
 
-This gives the agent file tools and shell tools automatically. The default workspace is per agent; subagents get nested workspace directories under their parent agent's workspace path.
+This gives the agent file tools and shell tools automatically. The default workspace is per agent. Subagents get nested workspace directories under their parent agent's workspace path.
 
 ## Quickstart
 

package/.docs/reference/logging/pino-logger.md

@@ -149,7 +149,7 @@ You can create custom transports using the `createCustomTransport` utility to in
 
 ### Sentry transport example
 
-Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.
+Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. The custom transport forwards logs to an external system such as Sentry for advanced monitoring and observability.
 
 ```typescript
 import { createCustomTransport } from '@mastra/core/loggers'

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

@@ -87,7 +87,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.
 
-**observation.blockAfter** (`number`): Safety net that forces a synchronous (blocking) observation when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 forces a blocking observation at 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Between messageTokens and blockAfter, only async buffering and activation run; buffered activation still preserves a minimum remaining context (the smaller of 1000 tokens or the retention floor). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
+**observation.blockAfter** (`number`): Safety net for when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 resolves to 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Above this point, activation uses the smallest set of buffered chunks that reaches the retention target, even when that overshoots the target by more than the usual safeguard allows. It never activates more chunks than are needed to reach the retention target, so it removes only slightly more history than a normal activation. It changes the result only when the retention floor is above roughly 20,000 tokens; with the default bufferActivation (a 6k floor) it has no observable effect. Activation usually keeps a minimum remaining context (the smaller of 1000 tokens or the retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less. Crossing blockAfter does not trigger a blocking observation. A synchronous (blocking) observation runs when the messageTokens threshold is reached and buffered activation did not happen. Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to 0 to omit previous observations entirely, or false to disable truncation explicitly.
 
@@ -353,7 +353,7 @@ export const agent = new Agent({
 
 Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
 
-The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. Above the `blockAfter` threshold, activation may overshoot the retention target instead of activating fewer chunks. If the threshold is reached and no buffered chunk activates, a synchronous observation runs instead.
 
 Default settings:
 
@@ -383,7 +383,7 @@ export const agent = new Agent({
           bufferTokens: 5_000,
           // Activate to retain 30% of threshold
           bufferActivation: 0.7,
-          // Force synchronous observation at 1.5x threshold
+          // Above 1.5x the threshold, let activation overshoot the retention target
           blockAfter: 1.5,
         },
         reflection: {
@@ -787,6 +787,8 @@ Mastra also injects scope-aware usage instructions into the agent's context. For
 
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \[p1] — call again with partIndex: 1 to see the full content without loading every part.
 
+**charOffset** (`number`): Character position to continue reading a truncated single part. Only applies with cursor and partIndex. When a part is larger than the token budget, the result includes nextCharOffset — pass that exact value here in the next call to read the following chunk. The chunks concatenate to the original part text. (Default: `0`)
+
 **before** (`string`): For mode: "threads" only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. "2026-03-15", "2026-03-10T00:00:00Z").
 
 **after** (`string`): For mode: "threads" only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. "2026-03-01", "2026-03-10T00:00:00Z").
@@ -809,10 +811,16 @@ Mastra also injects scope-aware usage instructions into the agent's context. For
 
 **hasPrevPage** (`boolean`): Whether more messages exist before this page.
 
-**truncated** (`boolean`): Present and true when the output was capped by the token budget. The agent can paginate or use partIndex to access remaining content.
+**truncated** (`boolean`): Present and true when the output was capped by the token budget. The agent can paginate or use partIndex to access remaining content. When a single part is itself too large, the partIndex result includes nextCharOffset for continuing within the part.
 
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when truncated is true.
 
+**charOffset** (`number`): On single-part results (partIndex), the character position this chunk starts at. 0 unless the call passed a charOffset.
+
+**nextCharOffset** (`number`): On single-part results, present when the part was truncated and more content remains. Pass this value as charOffset in the next call to continue reading from where this chunk ended.
+
+**note** (`string`): On truncated single-part results, the exact follow-up call for retrieving the next chunk.
+
 ### Returns (threads mode)
 
 **threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with ← current.

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

@@ -2,7 +2,7 @@
 
 # Agent class
 
-The Agent class has been updated with reorganized voice methods, updated property access patterns, and streamlined streaming APIs.
+The Agent class has been updated with reorganized voice methods and property access patterns, plus streamlined streaming APIs.
 
 ## Changed
 
@@ -70,7 +70,7 @@ To migrate, update all imports and parameter names from `RuntimeContext`/`runtim
 
 ### Direct property access to getter methods
 
-Direct property access to `agent.llm`, `agent.tools`, and `agent.instructions` is deprecated. This change provides better encapsulation and consistency with the broader API design.
+Direct property access to `agent.llm`, `agent.tools`, and `agent.instructions` is deprecated. The accessors improve encapsulation and align with the broader API design.
 
 To migrate, replace property access with the corresponding getter methods.
 
@@ -146,7 +146,7 @@ To migrate, update processor method names.
 
 Mastra v1 continues to accept both Zod v3 and Zod v4 schemas in public agent APIs that take structured output schemas. This includes methods such as `agent.generateLegacy()` and `agent.streamLegacy()` and the related option types.
 
-If you already pass Zod schemas to agent APIs, no migration is required for Zod version compatibility. Keep your existing schema imports:
+Existing Zod schemas passed to agent APIs don't require migration for Zod version compatibility. Keep your existing schema imports:
 
 ```ts
 import { z as z3 } from 'zod/v3'

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

@@ -148,7 +148,7 @@ client.memory.listMessages({
 
 ### `getMemoryThread` parameter structure
 
-The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
+The `getMemoryThread` method parameter structure has been updated. The new structure aligns the API across memory methods.
 
 To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
 

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

@@ -74,7 +74,7 @@ const scorer = createScorer({
 
 ### Scorer configuration from `name` to `id`
 
-Scorers now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities.
+Scorers now require an `id` field instead of `name`. The `name` field is now optional. The new field aligns scorers with other Mastra entities.
 
 To migrate, update scorer definitions to use `id` as the required field.
 

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

@@ -49,7 +49,7 @@ const mastra = new Mastra({
 
 ### Required `id` parameter for all mastra primitives
 
-All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.
+All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. Required IDs standardize the Mastra API and prevent ID conflicts.
 
 All these primitives also now have `get`, `list`, and `add` functions.
 

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

@@ -59,7 +59,7 @@ To migrate, replace all calls to `mcp.getToolsets()` with `mcp.listToolsets()`.
 
 ### MCP tool context properties organization
 
-Context properties in MCP tools are now organized under the `context.mcp` namespace. This change provides better organization and clearer API surface for MCP-specific functionality.
+Context properties in MCP tools are now organized under the `context.mcp` namespace. The namespace organizes MCP-specific functionality under a clear API surface.
 
 To migrate, access MCP-specific properties like `elicitation` and `extra` through `context.mcp` instead of directly from the context parameter.
 

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

@@ -108,7 +108,7 @@ Work through this checklist in order, starting with high-impact changes that aff
 - Update storage methods from `get*` to `list*` pattern - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
 - Replace direct property access with getter methods - [Mastra Class](https://mastra.ai/reference/migrations/upgrade-to-v1/mastra), [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
 - Update memory scope if relying on default `thread` scope - [Memory](https://mastra.ai/reference/migrations/upgrade-to-v1/memory)
-- Update vector store calls to use named arguments - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
+- Update vector store calls to use arguments by name - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
 - Remove `format` parameter from agent methods - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
 - Update voice methods to use `agent.voice` namespace - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
 - Rename configuration property `processors` to `spanOutputProcessors` (if using custom processors) - [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)

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

@@ -8,7 +8,7 @@ Processor interfaces have been updated to use consistent naming patterns and dat
 
 ### Processor configuration from `name` to `id`
 
-Processors now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities like scorers and agents.
+Processors now require an `id` field instead of `name`. The `name` field is now optional. The new field aligns processors with other Mastra entities such as scorers and agents.
 
 To migrate, update processor definitions to use `id` as the required field.
 

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

@@ -93,7 +93,7 @@ USING snapshot::jsonb;
 
 ### Storage composition in `MastraCompositeStore`
 
-`MastraCompositeStore` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
+`MastraCompositeStore` can now compose storage domains from different adapters. Use it when different purposes require different databases, such as PostgreSQL for memory and workflows with a specialized database for observability.
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'
@@ -386,7 +386,7 @@ To migrate, use the memory store, remove format parameters, and update code to w
 + const saved = saveResult?.messages; // MastraDBMessage[]
 ```
 
-### Vector store API from positional to named arguments
+### Vector store API from positional arguments to arguments by name
 
 All vector store methods now use an arguments object instead of positional arguments. This makes each value's purpose visible at the call site and lets method signatures evolve without relying on argument order.
 
@@ -430,7 +430,7 @@ To migrate, rename the methods and pass an arguments object.
 
 ### PGVector constructor from connection string to object
 
-The PGVector constructor now requires object parameters instead of a connection string. This change provides a more consistent API across all storage adapters.
+The PGVector constructor now requires object parameters instead of a connection string. Object parameters align the API across storage adapters.
 
 To migrate, pass the connection string as an object property.
 
@@ -484,7 +484,7 @@ const pgStore = new PostgresStore({
 
 ### Score storage methods to `listScoresBy*` pattern
 
-Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change provides consistency with the broader API naming conventions.
+Score storage APIs have been renamed to follow the `listScoresBy*` pattern. The new names follow the broader API naming conventions.
 
 To migrate, update method names from `getScores` to `listScoresByScorerId` and related variants.
 
@@ -500,7 +500,7 @@ To migrate, update method names from `getScores` to `listScoresByScorerId` and r
 
 ### Non-paginated storage functions
 
-Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. This change provides consistency across the API and prevents accidental loading of large datasets.
+Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. Pagination aligns list operations across the API and prevents accidental loading of large datasets.
 
 To migrate, use paginated methods via domain stores. For fetching all records, use `perPage: false`.
 

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

@@ -32,7 +32,7 @@ createTool({
 
 ### `createTool` context properties organization
 
-Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
+Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. The namespaces organize these properties under a clearer API surface.
 
 For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
 

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -78,7 +78,7 @@ Force-flushes any buffered LLM Observability data to Datadog without shutting do
 async shutdown(): Promise<void>
 ```
 
-Force-finishes any APM spans that weren't properly closed, flushes pending LLM Observability data, disables the LLM Observability integration, and clears all internal state.
+Force-finishes any APM spans that weren't properly closed and flushes pending LLM Observability data. It then disables the integration and clears all internal state.
 
 ## Usage examples
 

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -146,7 +146,7 @@ Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute:
 }
 ```
 
-This format ensures compatibility with all OTEL-compatible backends and collectors.
+The format is compatible with all OTEL-compatible backends and collectors.
 
 ## Related
 

package/.docs/reference/observability/tracing/exporters/arize.md

@@ -2,7 +2,7 @@
 
 # ArizeExporter
 
-Sends Tracing data to Arize Phoenix, Arize AX, or any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
+Sends Tracing data to Arize Phoenix or Arize AX, as well as any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
 
-> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
+> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior. `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
@@ -183,7 +183,7 @@ The exporter batches tracing spans, logs, metrics, scores, and feedback for effi
 ### Signal Processing
 
 - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
-- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for that signal type
 - All supported signal batches are uploaded to their matching Cloud publish endpoints during `flush()` and `shutdown()`
 
 ## `MastraCloudSpanRecord`

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -199,7 +199,7 @@ The probe timer doesn't keep the Node.js process alive, so short-lived and serve
 ### Signal Processing
 
 - `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
-- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for that signal type
 - All supported signal batches are uploaded to their matching publish endpoints during `flush()` and `shutdown()`
 
 ## Span wire format

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -2,7 +2,7 @@
 
 # OtelExporter
 
-Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions; logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
+Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions. Logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/sentry.md

@@ -51,7 +51,7 @@ Force flushes any pending spans to Sentry without shutting down the exporter. Wa
 async shutdown(): Promise<void>
 ```
 
-Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.
+Ends all active spans and clears internal state before closing the Sentry connection. Waits up to 2 seconds for pending data to be sent.
 
 ## Usage
 

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -57,7 +57,7 @@ new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
 
 **redactionToken** (`string`): Replacement value used for full redaction and short values under partial redaction. (Default: `'[REDACTED]'`)
 
-**redactionStyle** (`'full' | 'partial'`): Controls whether matched values are fully or partially redacted. (Default: `'full'`)
+**redactionStyle** (`'full' | 'partial' | 'indexed'`): Controls how matched values are redacted. (Default: `'full'`)
 
 ```typescript
 interface SensitiveDataFilterOptions {
@@ -66,7 +66,7 @@ interface SensitiveDataFilterOptions {
   redactionStyle?: RedactionStyle
 }
 
-type RedactionStyle = 'full' | 'partial'
+type RedactionStyle = 'full' | 'partial' | 'indexed'
 ```
 
 ## Redaction styles
@@ -101,6 +101,30 @@ const filter = new SensitiveDataFilter({
 { "apiKey": "sk-…789" }
 ```
 
+### Indexed redaction
+
+Indexed redaction replaces each unique value with a stable token derived from the first field name that matched it, for example `[APIKEY_1]`. The same value maps to the same token across the spans of a trace while the trace's mapping is retained, so redacted values stay correlatable without exposing the raw value. Later occurrences under other sensitive fields reuse the first token.
+
+```typescript
+const filter = new SensitiveDataFilter({
+  redactionStyle: 'indexed',
+})
+```
+
+```jsonc
+// Before (two spans in the same trace)
+[{ "apiKey": "sk-alice-key" }, { "apiKey": "sk-bob-key" }]
+
+// After
+[{ "apiKey": "[APIKEY_1]" }, { "apiKey": "[APIKEY_2]" }]
+```
+
+The mapping is scoped per trace. Numbering restarts for each trace, so tokens from different traces can't be linked.
+
+State is bounded in two ways. The filter keeps mappings for the 1000 most recently used traces. The least recently used trace is evicted beyond that, and spans arriving for an evicted trace start a fresh mapping, so later values may receive new tokens. Each trace also tracks up to 1000 unique values. Once that cap is reached, already-tracked values keep their tokens and new values are redacted with `redactionToken`.
+
+Non-string values are converted to strings before a token is assigned.
+
 ## Field matching
 
 Field names are lowercased and stripped of non-alphanumeric characters before comparison:
@@ -165,7 +189,7 @@ Returns: `AnySpan`
 
 #### `shutdown()`
 
-Completes processor shutdown. The current processor has no resources or state to clean up.
+Completes processor shutdown and clears the per-trace state used by indexed redaction.
 
 ```typescript
 await filter.shutdown()

package/.docs/reference/processors/batch-parts-processor.md

@@ -2,7 +2,7 @@
 
 # BatchPartsProcessor
 
-The `BatchPartsProcessor` is an **output processor** that batches multiple stream parts together to reduce the frequency of emissions during streaming. This processor is useful for reducing network overhead, improving user experience by consolidating small text chunks, and optimizing streaming performance by controlling when parts are emitted to the client.
+The `BatchPartsProcessor` is an **output processor** that batches multiple stream parts together to reduce the frequency of emissions during streaming. This processor is useful for reducing network overhead and consolidating small text chunks for users, while controlling emissions to optimize streaming performance.
 
 ## Usage example
 

package/.docs/reference/processors/language-detector.md

@@ -40,7 +40,7 @@ const processor = new LanguageDetector({
 
 **options.includeDetectionDetails** (`boolean`): Whether to include detailed detection info in logs
 
-**options.translationQuality** (`'speed' | 'quality' | 'balanced'`): Translation quality preference: 'speed' prioritizes fast translation, 'quality' prioritizes accuracy, 'balanced' balances between speed and quality
+**options.translationQuality** (`'speed' | 'quality' | 'balanced'`): Deprecated. This option previously selected prompt-level "Quality Level" guidance, but that behavior was removed when the detection and translation prompts were streamlined. The option now has no effect. For model-specific speed and quality controls, use providerOptions when your provider supports them.
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
@@ -74,7 +74,6 @@ export const agent = new Agent({
         'Detect language and translate non-English content to English while preserving original intent',
       minTextLength: 10,
       includeDetectionDetails: true,
-      translationQuality: 'quality',
     }),
   ],
 })

package/.docs/reference/processors/processor-interface.md

@@ -78,17 +78,17 @@ Processor methods run at different points in the agent execution lifecycle:
 └────────────────────────────────────────────────────────────────────┘
 ```
 
-| Method                | When it runs                                                                                | Use case                                                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `processInput`        | Once at the start, before the agentic loop                                                  | Validate/transform initial user input, add context                                             |
-| `processInputStep`    | At each step of the agentic loop, before each LLM call                                      | Transform messages between steps, handle tool results                                          |
-| `processLLMRequest`   | After LLM request conversion, before the provider call                                      | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
-| `processAPIError`     | When an LLM API call fails                                                                  | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
-| `processOutputStream` | On each streaming chunk during LLM response                                                 | Filter/modify streaming content, detect patterns in real-time                                  |
-| `processLLMResponse`  | After the LLM step completes and stream chunks are collected                                | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
-| `processOutputStep`   | After each LLM response, before tool execution                                              | Validate output quality, implement guardrails with retry                                       |
-| `processToolResult`   | Per tool, after `tool.execute()` returns and before the result is added to the message list | Scan tool output for prompt injection, redact sensitive fields, abort on policy violations     |
-| `processOutputResult` | Once after generation completes                                                             | Post-process final response, log results                                                       |
+| Method                | When it runs                                                                                                                               | Use case                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `processInput`        | Once at the start, before the agentic loop                                                                                                 | Validate/transform initial user input, add context                                             |
+| `processInputStep`    | At each step of the agentic loop, before each LLM call                                                                                     | Transform messages between steps, handle tool results                                          |
+| `processLLMRequest`   | After LLM request conversion, before the provider call                                                                                     | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
+| `processAPIError`     | When an LLM API call fails                                                                                                                 | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
+| `processOutputStream` | On each streaming chunk during LLM response                                                                                                | Filter/modify streaming content, detect patterns in real-time                                  |
+| `processLLMResponse`  | After the LLM step completes and stream chunks are collected                                                                               | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
+| `processOutputStep`   | After each LLM response, before tool execution                                                                                             | Validate output quality, implement guardrails with retry                                       |
+| `processToolResult`   | Per tool, after a locally executed tool returns or a provider-executed result arrives, before the raw result is persisted to `messageList` | Inspect tool output and enforce security policies                                              |
+| `processOutputResult` | Once after generation completes                                                                                                            | Post-process final response, log results                                                       |
 
 ## Interface definition
 
@@ -212,7 +212,7 @@ function getText(message: MastraDBMessage): string {
 
 Key points:
 
-- `message.content.parts` is the primary source. A single message can contain multiple parts, including non-text parts such as tool calls, tool results, and file parts. Filter by `part.type === 'text'` before reading `part.text`.
+- `message.content.parts` is the primary source. A single message can contain multiple parts. Non-text parts include tool calls and tool results, plus file parts. Filter by `part.type === 'text'` before reading `part.text`.
 - `message.content.content` is a flattened string kept for backward compatibility. Use it only as a fallback when `parts` is empty or missing.
 - `message.content` itself is never a plain string on `MastraDBMessage`. Legacy `CoreMessage` shapes may be strings, but processors always receive `MastraDBMessage`.
 
@@ -365,7 +365,7 @@ System messages are **reset to their original values** at the start of each step
 #### Use cases
 
 - Dynamic model switching based on step number or context
-- Disabling tools after a certain number of steps
+- Disabling tools after a configured number of steps
 - Dynamically adding or replacing tools based on conversation context
 - Transforming message part types between providers (e.g., `reasoning` → `thinking` for Anthropic)
 - Modifying messages based on step number or accumulated context
@@ -708,11 +708,11 @@ export class QualityGuardrail implements Processor {
 
 ### `processToolResult`
 
-Processes a tool's result after `tool.execute()` returns and before the result is added to the message list or fed to the next LLM call. Symmetric with `processOutputStep`, which fires before tool execution. Use this method to scan tool output for prompt injection, redact sensitive fields, or abort the run with `abort('reason', { retry: true })`.
+Processes a tool's result after a locally executed tool returns or a provider-executed result arrives, before the raw result is persisted to `messageList` or fed to the next LLM call. Symmetric with `processOutputStep`, which fires before tool execution. Use this method to enforce security policies on tool output. For example, scan for prompt injection or redact sensitive fields. Call `abort('reason', { retry: true })` to abort and retry the same step.
 
-To replace the tool's result, mutate `messageList` in place via `messageList.updateToolInvocation`. The runtime re-reads the post-processor result from the message list and overwrites the downstream tool-result stream chunk before it is enqueued, so streaming clients see the processed value.
+To replace the tool's result, mutate `messageList` in place via `messageList.updateToolInvocation`. The runtime re-reads the post-processor result from the message list and overwrites the downstream tool-result stream chunk before it's enqueued, so streaming clients see the processed value.
 
-This method does not fire when `tool.execute()` throws; it is called only for successful tool executions where a result is available.
+This method doesn't fire when `tool.execute()` throws. It's called only for successful tool executions where a result is available.
 
 ```typescript
 processToolResult?(args: ProcessToolResultArgs): ProcessorMessageResult;

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -49,7 +49,7 @@ For retryable errors with a `Retry-After` response header, the processor reads c
 
 ## Retry unknown errors
 
-Set `retryUnknownErrors` to retry errors that don't match provider metadata, the built-in OpenAI matcher, or a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:
+Set `retryUnknownErrors` to retry errors that don't match provider metadata or the built-in OpenAI matcher, including a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -105,7 +105,7 @@ export const agent = new Agent({
 
 ## Default OpenAI Responses matcher
 
-`isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes and, as a fallback, errors with explicit retry guidance such as `You can retry your request`.
+`isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes. As a fallback, it retries errors with explicit retry guidance such as `You can retry your request`.
 
 `StreamErrorRetryProcessor` includes this matcher by default. You can also import it and reuse it in custom retry logic.
 

package/.docs/reference/rag/chunking-and-embedding.md

@@ -127,7 +127,7 @@ const { embeddings } = await embedMany({
 })
 ```
 
-> **Vector Database Compatibility:** When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions don't match, you may get errors or data corruption.
+> **Vector Database Compatibility:** When storing embeddings, configure the vector database index to match the output size of your embedding model to avoid errors or data corruption from mismatched dimensions.
 
 ## Example: Complete pipeline
 

package/.docs/reference/rag/metadata-filters.md

@@ -201,7 +201,7 @@ const results = await store.query({
 ### Amazon S3 Vectors
 
 - Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date aren't allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
-- `$in`/`$nin` require **non-empty arrays of primitives**; Date elements are allowed and normalized to epoch ms. **Array equality** isn't supported.
+- `$in`/`$nin` require **non-empty arrays of primitives**. Date elements are allowed and normalized to epoch ms. **Array equality** isn't supported.
 - Implicit AND is canonicalized (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]`). Logical operators must contain field conditions and use non-empty arrays. They may appear only at the root or within other logical operators (not inside field values).
 - Keys listed in `nonFilterableMetadataKeys` at index creation are stored but not filterable. This setting is immutable.
 - $exists requires a boolean value.

package/.docs/reference/server/koa-adapter.md

@@ -76,7 +76,7 @@ app.listen(3000, () => {
 
 ## Error handling
 
-The Koa adapter propagates errors from route handlers up through Koa's middleware chain, following Koa's standard error handling pattern. This means you can use regular Koa error-handling middleware:
+The Koa adapter propagates errors from route handlers up through Koa's middleware chain, following Koa's standard error handling pattern. You can use regular Koa error-handling middleware:
 
 ```typescript
 const app = new Koa()

package/.docs/reference/signals/webhook-signal-provider.md

@@ -100,7 +100,7 @@ Returns: `boolean`
 
 #### `handleWebhook(request)`
 
-Process an incoming webhook request. Extracts the resource ID from the payload, finds matching subscriptions, builds a notification for each, and calls `notify()`.
+Process an incoming webhook request. Extracts the resource ID from the payload and finds matching subscriptions. It builds a notification for each subscription and calls `notify()`.
 
 ```typescript
 const result = await webhookProvider.handleWebhook({

package/.docs/reference/storage/retention.md

@@ -234,7 +234,7 @@ const storage = new MongoDBStore({
 
 `prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing: for most users this alone solves the unbounded-growth problem.
 
-Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
+Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically. A manual `VACUUM FULL` is only needed if you must return disk to the OS.
 
 For MongoDB, deleted documents are reused by future insertions. To reclaim disk space, run [`db.runCommand({ compact: "collection_name" })`](https://www.mongodb.com/docs/manual/reference/command/compact/) during a maintenance window.
 

package/.docs/reference/tools/bedrock-kb-tool.md

@@ -65,7 +65,7 @@ The tool returns an object with:
 | ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
 | `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
-| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval, which the agentic API omits from result items.                                    |
 | `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
 
 ## Retrieval Modes