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

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -12,7 +12,7 @@ Metrics are extracted from spans when they end. The observability layer inspects
 
 ### What affects whether a metric is available
 
-Two conditions must be true for a metric to reach storage:
+A metric reaches storage when:
 
 1. `MastraStorageExporter` is configured as an exporter.
 2. The storage backend supports metrics (ClickHouse, DuckDB, or Postgres v-next with the observability domain enabled).
@@ -33,7 +33,7 @@ Duration metrics record execution time in milliseconds, calculated from the span
 
 ## Token usage metrics
 
-Token metrics are emitted only from `MODEL_GENERATION` spans that include `usage` data. If the provider doesn't report usage, no token metrics are emitted for that span.
+Token metrics are emitted only from `MODEL_GENERATION` spans that include `usage` data. Token metrics require usage data from the provider.
 
 ### Input token metrics
 
@@ -64,7 +64,7 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. The registry ships with Mastra and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
+Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. Mastra includes the registry and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
 
 ### What cost fields may be included
 
@@ -80,9 +80,9 @@ Cost context is attached to token metrics when the embedded pricing registry has
 
 ### How metrics relate to spans and trace context
 
-Each metric carries a `CorrelationContext` snapshot from the span that produced it. This context is stored alongside the metric value and lets you navigate from a metric to the exact span and trace.
+Each metric carries a `CorrelationContext` snapshot from the span that produced it. This context is stored alongside the metric value and links a metric to the exact span and trace.
 
-The correlation fields are grouped into four categories:
+Correlation fields use these categories:
 
 **Trace correlation**
 
@@ -110,7 +110,7 @@ The correlation fields are grouped into four categories:
 
 ### Why correlation helps with debugging
 
-When you spot a spike in latency or token usage on the Metrics dashboard, correlation context lets you drill directly into the trace that produced the metric. From there you can inspect the individual span to find the root cause: a slow tool call, a large prompt, or an unexpected error.
+When you spot a spike in latency or token usage on the Metrics dashboard, correlation context lets you drill directly into the trace that produced the metric. From there you can inspect the individual span. The root cause might be a slow tool call or a large prompt. It might also be an unexpected error.
 
 ## Troubleshooting
 
@@ -129,7 +129,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ### Token metrics are missing
 
 - **Span is a model generation**: Token metrics are only emitted from `MODEL_GENERATION` spans.
-- **Provider reports usage**: The model provider must include `usage` data in its response. If usage is absent, no token metrics are emitted.
+- **Provider reports usage**: The model provider must include `usage` data in its response. Usage data is required to emit token metrics.
 
 ## Related
 

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

@@ -40,7 +40,7 @@ Extends `BaseExporterConfig`, which includes:
 createSpan(options: CreateSpanOptions<SpanType>): SpanIds | undefined
 ```
 
-Called by the Mastra observability instance during span construction. Creates a dd-trace APM span eagerly via `tracer.startSpan()` and returns Mastra-compatible identifiers. The returned IDs are used by Mastra throughout the span's lifetime; the dd-trace span object is stored internally and used for scope activation.
+Called by the Mastra observability instance during span construction. Creates a dd-trace APM span eagerly via `tracer.startSpan()` and returns Mastra-compatible identifiers. The returned IDs are used by Mastra throughout the span's lifetime. The dd-trace span object is stored internally and used for scope activation.
 
 **Returns:** `SpanIds | undefined` - `{ spanId, traceId, parentSpanId }`, or `undefined` if the bridge is disabled.
 
@@ -151,7 +151,7 @@ const mastra = new Mastra({
 })
 ```
 
-> **Note:** Don't combine `DatadogBridge` with `DatadogExporter` in the same configuration — both emit to LLM Observability and would double-write the same data.
+> **Note:** Don't combine `DatadogBridge` with `DatadogExporter` in the same configuration. Both emit to LLM Observability and would double-write the same data.
 
 ## Setup requirements
 

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. The two 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.
 
@@ -106,7 +106,7 @@ async onMetricEvent(event: MetricEvent): Promise<void>
 
 Processes metric signals for Cloud export.
 
-Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. Additional filtering by metric subtype or status inside `CloudExporter` isn't performed; the exporter forwards every metric event it receives unless it's disabled.
+Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. Additional filtering by metric subtype or status inside `CloudExporter` isn't performed. The exporter forwards every metric event it receives unless it's disabled.
 
 **Returns:** `Promise<void>` after the metric event has been accepted for buffering.
 
@@ -130,7 +130,7 @@ async onFeedbackEvent(event: FeedbackEvent): Promise<void>
 
 Processes feedback signals for Cloud export.
 
-Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `CloudExporter` is performed; all feedback events received here are forwarded unless the exporter is disabled.
+Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `CloudExporter` is performed. All feedback events received here are forwarded unless the exporter is disabled.
 
 **Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
 

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

@@ -4,7 +4,7 @@
 
 **Deprecated in `@mastra/observability@1.12.0`** in favor of [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter).
 
-> **Deprecated:** `DefaultExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter) for new projects. The two classes share the same constructor, configuration, and runtime behavior; `DefaultExporter` keeps its original `mastra-default-observability-exporter` exporter `name` so monitoring rules built against it keep working.
+> **Deprecated:** `DefaultExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter) for new projects. Both classes share the same constructor, configuration, and runtime behavior. `DefaultExporter` keeps its original `mastra-default-observability-exporter` exporter `name` so monitoring rules built against it keep working.
 
 Persists observability events to Mastra Storage with automatic batching and retry logic.
 

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

@@ -108,7 +108,7 @@ async onMetricEvent(event: MetricEvent): Promise<void>
 
 Processes metric signals for export.
 
-Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. No additional filtering by metric subtype or status inside `MastraPlatformExporter` is performed; the exporter forwards every metric event it receives unless it's disabled.
+Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. No additional filtering by metric subtype or status inside `MastraPlatformExporter` is performed. The exporter forwards every metric event it receives unless it's disabled.
 
 **Returns:** `Promise<void>` after the metric event has been accepted for buffering.
 
@@ -132,7 +132,7 @@ async onFeedbackEvent(event: FeedbackEvent): Promise<void>
 
 Processes feedback signals for export.
 
-Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `MastraPlatformExporter` is performed; all feedback events received here are forwarded unless the exporter is disabled.
+Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `MastraPlatformExporter` is performed. All feedback events received here are forwarded unless the exporter is disabled.
 
 **Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
 
@@ -192,7 +192,7 @@ Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `
 
 ## Span wire format
 
-The shape of each span sent to Mastra platform is documented here for reference only — it's not exported from `@mastra/observability` and shouldn't be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
+The shape of each span sent to Mastra platform is documented here for reference only: it's not exported from `@mastra/observability` and shouldn't be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
 
 ```typescript
 type MastraPlatformSpanRecord = AnyExportedSpan & {
@@ -231,7 +231,7 @@ const customExporter = new MastraPlatformExporter({
 
 ## Migrating from `CloudExporter`
 
-The two classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:
+Both classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:
 
 ```typescript
 // Before

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

@@ -162,7 +162,7 @@ const customExporter = new MastraStorageExporter({
 
 ## Migrating from `DefaultExporter`
 
-The two classes share the same constructor signature and behavior. To migrate, replace the import and constructor:
+Both classes share the same constructor signature and behavior. To migrate, replace the import and constructor:
 
 ```typescript
 // Before

package/.docs/reference/observability/tracing/interfaces.md

@@ -803,7 +803,7 @@ interface CustomSamplerOptions {
 
 ### `ConfigSelector`
 
-Function to select which observability instance to use for a given span.
+Function to select which observability instance to use for a span.
 
 ```typescript
 type ConfigSelector = (

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

@@ -22,7 +22,7 @@ new Observability({
 })
 ```
 
-If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values aren't modified — add a `SensitiveDataFilter` to their processors yourself if needed.
+If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values aren't modified. Add a `SensitiveDataFilter` to their processors yourself if needed.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/span-filtering.md

@@ -2,7 +2,7 @@
 
 # Span filtering
 
-Span filtering controls which spans are exported from an observability config. Use it to reduce noise, lower per-span costs, or keep only the spans that matter for a specific exporter or environment.
+Span filtering controls which spans are exported from an observability config. Use it to reduce noise or lower per-span costs. It can also keep only the spans that matter for a specific exporter or environment.
 
 For a shorter overview of tracing configuration, see [Tracing](https://mastra.ai/docs/observability/tracing/overview).
 

package/.docs/reference/processors/cost-guard-processor.md

@@ -14,7 +14,7 @@ Supports three scoping modes:
 - **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
 - **Thread scope**: Tracks cumulative cost per `threadId` across runs
 
-> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as a best-effort threshold, not a hard ceiling.
+> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as an approximate threshold that fast-running agents may exceed.
 
 ## Usage example
 

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

@@ -2,7 +2,7 @@
 
 # PIIDetector
 
-The `PIIDetector` is a **hybrid processor** that can be used for both input and output processing to detect and redact personally identifiable information (PII) for privacy compliance. This processor helps maintain privacy by identifying various types of PII and providing flexible strategies for handling them, including multiple redaction methods to ensure compliance with GDPR, CCPA, HIPAA, and other privacy regulations.
+The `PIIDetector` is a **hybrid processor** that can be used for both input and output processing to detect and redact personally identifiable information (PII) for privacy compliance. This processor helps maintain privacy by identifying types of PII and providing flexible strategies for handling them, including multiple redaction methods to ensure compliance with GDPR, CCPA, HIPAA, and other privacy regulations.
 
 ## Usage example
 

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

@@ -6,7 +6,7 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
 
 ## When processor methods run
 
-The eight processor methods run at different points in the agent execution lifecycle:
+Processor methods run at different points in the agent execution lifecycle:
 
 ```text
 ┌────────────────────────────────────────────────────────────────────┐
@@ -168,16 +168,16 @@ Use `messages` when you only need to read, map over, or lightly edit fields on t
 
 ### Persistence
 
-When memory is enabled, only what ends up in `messageList` after all processors finish is persisted to storage. The two return styles are equivalent for persistence:
+When memory is enabled, only what ends up in `messageList` after all processors finish is persisted to storage. Both return styles are equivalent for persistence:
 
-- Mutating `messageList` directly (or returning the same `MessageList` instance) — recorded mutations are applied in place, so the saved conversation reflects your changes.
-- Returning a `MastraDBMessage[]` or `{ messages, systemMessages }` — Mastra reconciles the returned array against `messageList` for the current stage, removing missing messages and replacing system messages.
+- When you mutate `messageList` directly (or return the same `MessageList` instance), recorded mutations are applied in place, so the saved conversation reflects your changes.
+- When you return a `MastraDBMessage[]` or `{ messages, systemMessages }`, Mastra reconciles the returned array against `messageList` for the current stage, removing missing messages and replacing system messages.
 
-Returning a different `MessageList` instance is an error; always mutate the one passed to your processor.
+Returning a different `MessageList` instance is an error. Always mutate the one passed to your processor.
 
 ### Reading text from a message
 
-`MastraDBMessage.content` is a structured object, not a string. The canonical way to read user or assistant text is `content.parts`:
+`MastraDBMessage.content` uses a structured object. Strings aren't supported. The canonical way to read user or assistant text is `content.parts`:
 
 ```typescript
 import type { MastraDBMessage } from '@mastra/core/memory'
@@ -313,10 +313,10 @@ processInputStep?<TTripwireMetadata = unknown>(
 
 `processInputStep` can return several shapes:
 
-- **`ProcessInputStepResult` object** — override any combination of the properties below for this step (described next).
-- **`MessageList`** — return the same `messageList` instance to signal you mutated messages in place.
-- **`MastraDBMessage[]`** — return a transformed messages array; replaces the step's messages.
-- **`void` or `undefined`** — return nothing to leave the step unchanged.
+- **`ProcessInputStepResult` object**: Override any combination of the properties below for this step (described next).
+- **`MessageList`**: Return the same `messageList` instance to signal you mutated messages in place.
+- **`MastraDBMessage[]`**: Return a transformed messages array. Replaces the step's messages.
+- **`void` or `undefined`**: Return nothing to leave the step unchanged.
 
 The object form can return any combination of these properties:
 
@@ -480,7 +480,7 @@ Handles LLM API rejection errors before they surface as final errors. This runs
 
 Add processors that implement `processAPIError` to an agent's `errorProcessors` array.
 
-Processors can inspect the error, modify the request (for example, by appending messages to the `messageList`), and return `{ retry: true }` to signal a retry with the modified state.
+Processors can inspect the error and modify the request, for example by appending messages to the `messageList`. Return `{ retry: true }` to retry with the modified state.
 
 ```typescript
 processAPIError?(args: ProcessAPIErrorArgs): Promise<ProcessAPIErrorResult | void> | ProcessAPIErrorResult | void;
@@ -896,7 +896,7 @@ export class WordCounter implements Processor {
 
 Every processor receives a `state` object in `processLLMRequest`, `processLLMResponse`, `processOutputStream`, `processOutputStep`, `processOutputResult`, and `processAPIError`. State has three important properties:
 
-- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Two processors with different ids can't read or overwrite each other's state.
+- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Processors with different ids can't read or overwrite each other's state.
 - **Per-request**: A fresh state object is created at the start of every `agent.generate()` or `agent.stream()` call. State doesn't leak between requests or between users.
 - **Shared across methods**: Within one request, the same `state` object is passed to `processLLMRequest` (before the provider call), `processLLMResponse` (after the step completes), `processOutputStream` (for every chunk), `processOutputStep` (after every LLM step), `processOutputResult` (once at the end), and `processAPIError` (when an LLM call fails). For example, `processLLMRequest` can stash a cache key and `processLLMResponse` can read it back to write the response.
 

package/.docs/reference/processors/prompt-injection-detector.md

@@ -2,7 +2,7 @@
 
 # PromptInjectionDetector
 
-The `PromptInjectionDetector` is an **input processor** that detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts before messages are sent to the language model. This processor helps maintain security by identifying various types of injection attempts and providing flexible strategies for handling them, including content rewriting to neutralize attacks while preserving legitimate user intent.
+The `PromptInjectionDetector` is an **input processor** that detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts before messages are sent to the language model. This processor helps maintain security by identifying types of injection attempts and providing flexible strategies for handling them, including content rewriting to neutralize attacks while preserving legitimate user intent.
 
 ## Usage example
 

package/.docs/reference/processors/provider-history-compat.md

@@ -4,7 +4,7 @@
 
 The `ProviderHistoryCompat` processor handles provider-specific history incompatibilities. It can rewrite the outbound language model prompt before a provider call, or react to API errors and retry with repaired message history.
 
-Use it when an agent may switch between model providers, reuse message history across providers, or call a provider that rejects fields emitted by another provider.
+Use it when an agent may switch between model providers or reuse message history across providers. It also handles providers that reject fields emitted by another provider.
 
 ## Usage example
 

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

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

package/.docs/reference/processors/response-cache.md

@@ -2,11 +2,11 @@
 
 # ResponseCache
 
-`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` (cache lookup; short-circuits on hit) and `processLLMResponse` (cache write on completion).
+`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` for cache lookup and short-circuits on a hit. It uses `processLLMResponse` to write the completed response.
 
-The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have transformed the prompt — so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
+The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model (i.e. _after_ memory has loaded and earlier input processors have transformed the prompt) so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
 
-No agent-level option for response caching exists; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
+No agent-level option for response caching exists. Register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
 
 ## Usage example
 
@@ -55,7 +55,7 @@ See [Response caching](https://mastra.ai/docs/agents/processors) for the concept
 
 ## Static helpers
 
-`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail — prefer them over reading/writing the raw key.
+`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail: prefer them over reading/writing the raw key.
 
 ### `ResponseCache.context(options)`
 
@@ -88,7 +88,7 @@ The shape passed to `ResponseCache.context()` / `ResponseCache.applyContext()`.
 
 **bust** (`boolean`): Skip the cache read but still write on completion.
 
-`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they're instance-level concerns that shouldn't vary per request.
+`cache`, `ttl`, and `agentId` are intentionally not overridable per call: they're instance-level concerns that shouldn't vary per request.
 
 ## ResponseCacheKeyInputs
 
@@ -106,9 +106,9 @@ The argument passed to a `key` function (constructor or per-call). All fields co
 
 ## Helper exports
 
-- `buildResponseCacheKey(inputs)` — the deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
-- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS` — the default `ttl` (`300`).
-- `RESPONSE_CACHE_CONTEXT_KEY` — the `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline); prefer the helpers.
+- `buildResponseCacheKey(inputs)`: The deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
+- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS`: The default `ttl` (`300`).
+- `RESPONSE_CACHE_CONTEXT_KEY`: The `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline). Prefer the helpers.
 
 ## Related
 

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -2,7 +2,7 @@
 
 # SystemPromptScrubber
 
-The `SystemPromptScrubber` is an **output processor** that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying various types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.
+The `SystemPromptScrubber` is an **output processor** that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.
 
 ## Usage example
 

package/.docs/reference/processors/token-limiter-processor.md

@@ -94,7 +94,7 @@ export const agent = new Agent({
 
 ### As a per-step input processor (limit multi-step token growth)
 
-When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop — the `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
+When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop. The `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'

package/.docs/reference/processors/tool-search-processor.md

@@ -2,7 +2,7 @@
 
 # ToolSearchProcessor
 
-The `ToolSearchProcessor` is an **input processor** that enables dynamic tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (`search_tools` and `load_tool`) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.
+The `ToolSearchProcessor` is an **input processor** that enables runtime-defined tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (`search_tools` and `load_tool`) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.
 
 ## Usage example
 
@@ -91,11 +91,11 @@ Immediately runs TTL cleanup instead of waiting for the scheduled sweep.
 const cleaned = processor.cleanupNow()
 ```
 
-Returns: `number` — the count of threads cleaned up.
+Returns: `number`: the count of threads cleaned up.
 
 ## Request-aware filtering
 
-Use `filter` to apply request-specific policy to dynamic tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
+Use `filter` to apply request-specific policy to runtime-defined tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
 
 ```typescript
 import { ToolSearchProcessor } from '@mastra/core/processors'
@@ -120,7 +120,7 @@ The `phase` value describes where the filter is being applied:
 - `load`: Blocks `load_tool` from loading disallowed tools.
 - `active`: Hides already-loaded tools from the current request if they're no longer allowed.
 
-If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available; `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
 
 ## Extended usage example
 
@@ -188,7 +188,7 @@ Every match is activated, so keep `topK` small (for example, `3`) to avoid addin
 
 ## Loaded-tool storage
 
-The `storage` option controls where the set of loaded tools is tracked. The default is `'in-memory'`; the `'context'` store is opt-in.
+The `storage` option controls where the set of loaded tools is tracked. The default is `'in-memory'`. The `'context'` store is opt-in.
 
 ### `'in-memory'` (default)
 
@@ -205,7 +205,7 @@ Use `clearState`, `clearAllState`, `getStateStats`, and `cleanupNow` to inspect
 Loaded state is derived from the conversation messages: a tool is loaded while a `search_tools` or `load_tool` result naming it remains in the messages. This mode:
 
 - Requires no memory configuration.
-- Is restart-safe — the durable record is the persisted message history.
+- Is restart-safe: the durable record is the persisted message history.
 - De-loads a tool automatically once that result is no longer present in the messages.
 
 ```typescript
@@ -219,7 +219,7 @@ const toolSearch = new ToolSearchProcessor({
 
 Loading tools is cache-friendly in both modes: loads are append-only, so the cached prompt prefix stays stable for providers that support prompt caching.
 
-Unloading a tool changes the tool definitions sent to the model, which shifts the cached prefix and causes the next turn to pay a cache write instead of a cache hit. In `'in-memory'` mode this happens when a thread's state is evicted by `ttl`. In `'context'` mode it happens when a tool's discovery result is no longer present in the messages (for example, when older messages are trimmed) — the tool de-loads and the model must search for it again before reuse. This is expected: removing an unused tool trades one cache write for a smaller prefix on later turns.
+Unloading a tool changes the tool definitions sent to the model, which shifts the cached prefix and causes the next turn to pay a cache write instead of a cache hit. In `'in-memory'` mode this happens when a thread's state is evicted by `ttl`. In `'context'` mode it happens when a tool's discovery result is no longer present in the messages (for example, when older messages are trimmed). The tool de-loads, and the model must search for it again before reuse. This is expected: removing an unused tool trades one cache write for a smaller prefix on later turns.
 
 ## Combining with other processors
 

package/.docs/reference/processors/unicode-normalizer.md

@@ -2,7 +2,7 @@
 
 # UnicodeNormalizer
 
-The `UnicodeNormalizer` is an **input processor** that normalizes Unicode text to ensure consistent formatting and remove potentially problematic characters before messages are sent to the language model. This processor helps maintain text quality by handling various Unicode representations, removing control characters, and standardizing whitespace formatting.
+The `UnicodeNormalizer` is an **input processor** that normalizes Unicode text to ensure consistent formatting and remove potentially problematic characters before messages are sent to the language model. This processor handles Unicode representations and removes control characters. It also standardizes whitespace formatting.
 
 ## Usage example
 

package/.docs/reference/project-structure.md

@@ -4,7 +4,7 @@
 
 Your new Mastra project, created with the `create mastra` command, comes with a predefined set of files and folders to help you get started.
 
-Mastra is a framework, but it's mostly **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
+Mastra is a framework, but it's mostly **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to browse.
 
 ## Default project structure
 

package/.docs/reference/pubsub/base.md

@@ -77,7 +77,7 @@ await pubsub.publish('my-topic', {
 
 Registers a callback to receive events published to a topic. When `options.group` is set, subscribers in the same group compete for messages and each event is delivered to one member. Without a group, every subscriber receives every event.
 
-Pass `options.batch` to opt in to batched delivery. The callback signature is unchanged: a batch of N events is delivered as N consecutive `cb(event, ack, nack)` calls in publish order. Batching is honored only when the backend's [`supportsNativeBatching`](#properties) is `true`; other backends ignore the option and deliver events one at a time.
+Pass `options.batch` to opt in to batched delivery. The callback signature is unchanged: a batch of N events is delivered as N consecutive `cb(event, ack, nack)` calls in publish order. Batching is honored only when the backend's [`supportsNativeBatching`](#properties) is `true`. Other backends ignore the option and deliver events one at a time.
 
 ```typescript
 await pubsub.subscribe('my-topic', (event, ack, nack) => {
@@ -103,9 +103,9 @@ await pubsub.flush()
 
 #### `clearTopic(topic)`
 
-Deletes all retained state for a topic — cached history, persistent stream entries, and consumer groups — once no more events will be published to it. Mastra's run lifecycles (durable agents and the evented workflow engine) call this automatically when a run reaches a terminal state, so per-run topics don't accumulate on transports that retain messages.
+Deletes all retained state for a topic (cached history, persistent stream entries, and consumer groups) once no more events will be published to it. Mastra's run lifecycles (durable agents and the evented workflow engine) call this automatically when a run reaches a terminal state, so per-run topics don't accumulate on transports that retain messages.
 
-The default implementation is a no-op: transports that retain nothing per topic (such as `EventEmitterPubSub`) have nothing to clear. Backends that persist messages, like [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), override it. The contract is best-effort — implementations log failures rather than throwing, because callers invoke it fire-and-forget at cleanup boundaries.
+The default implementation is a no-op: transports that retain nothing per topic (such as `EventEmitterPubSub`) have nothing to clear. Backends that persist messages, like [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), override it. The contract is best-effort: implementations log failures rather than throwing, because callers invoke it fire-and-forget at cleanup boundaries.
 
 ```typescript
 await pubsub.clearTopic('workflow.events.v2.run-123')
@@ -177,7 +177,7 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
 
 ### `SubscribeBatchOptions`
 
-Per-subscription batching policy. The callback signature doesn't change; a batch of N events becomes N consecutive callback invocations in publish order.
+Per-subscription batching policy. The callback signature doesn't change. A batch of N events becomes N consecutive callback invocations in publish order.
 
 **maxSize** (`number`): Maximum events held before forcing a flush.
 

package/.docs/reference/pubsub/google-cloud-pubsub.md

@@ -6,7 +6,7 @@
 
 Use it for distributed deployments on Google Cloud. For single-process delivery, use [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). For Redis, use [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams).
 
-Each topic maps to a Google Cloud topic. Subscriptions with a group share a named subscription, so members compete for events. Subscriptions without a group create a per-instance subscription, so every instance receives every event.
+Each topic maps to a Google Cloud topic. Subscriptions with a group share a subscription, so members compete for events. Subscriptions without a group create a per-instance subscription, so every instance receives every event.
 
 ## Installation
 
@@ -85,7 +85,7 @@ await pubsub.flush()
 
 ### `destroy(topicName)`
 
-Removes the subscription and topic for a given topic name. Use this to clean up Google Cloud resources.
+Removes the subscription and topic for a topic name. Use this to clean up Google Cloud resources.
 
 ```typescript
 await pubsub.destroy('workflow.events')

package/.docs/reference/pubsub/lease-provider.md

@@ -2,9 +2,9 @@
 
 # LeaseProvider
 
-`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a given resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
+`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
 
-Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can genuinely coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that can't lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
+Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can actually coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that can't lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
 
 The built-in [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) implements `LeaseProvider`, which is what enables signals to coordinate across instances in distributed and serverless deployments.
 
@@ -102,7 +102,7 @@ Returns: `Promise<boolean>`
 
 #### `transferLease(key, fromOwner, toOwner, ttlMs)`
 
-Atomically hands a held lease from `fromOwner` to `toOwner`, refreshing its TTL, without releasing the key in between. This is the gap-free primitive used when one owner finishes but a follow-up owner must take over the same key immediately, for example when a thread run completes and a queued follow-up run drains on the same thread. A naive release-then-acquire would briefly leave the key empty, letting a racing process win the freed lease and start a competing run.
+Atomically transfers a held lease from `fromOwner` to `toOwner` and refreshes its TTL without releasing the key in between. This gap-free primitive lets a follow-up owner take over the same key immediately after the current owner finishes. For example, a queued follow-up run can take over when a thread run completes. A naive release-then-acquire briefly leaves the key empty. A racing process could then win the freed lease and start a competing run.
 
 Returns `true` if `fromOwner` still held the lease and ownership moved to `toOwner`, or `false` if the lease was already lost, in which case the caller should fall back to a fresh `acquireLease`.
 
@@ -129,5 +129,5 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
-- [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread runs across processes
+- [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread execution across processes
 - [Channels](https://mastra.ai/docs/capabilities/channels/overview): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/reference/pubsub/redis-streams.md

@@ -101,7 +101,7 @@ await pubsub.flush()
 
 ### `clearTopic(topic)`
 
-Deletes a topic's stream and every consumer group on it, freeing the memory a finished topic would otherwise hold. Mastra's run lifecycles — durable agents and the evented workflow engine — call this automatically when a run reaches a terminal state; call it yourself only once nothing will read the topic again. It's best-effort and never throws — failures are logged at warn level. A subscriber still attached when the stream is deleted recovers on its own but misses the deleted entries.
+Deletes a topic's stream and every consumer group on it, freeing the memory a finished topic would otherwise hold. Mastra's run lifecycles (durable agents and the evented workflow engine) call this automatically when a run reaches a terminal state. Call it yourself only once nothing will read the topic again. It's best-effort and never throws. Failures are logged at warn level. A subscriber still attached when the stream is deleted recovers on its own but misses the deleted entries.
 
 Automatic cleanup requires `@mastra/core` and `@mastra/redis-streams` versions that both support `clearTopic`: the runtime routes the call through its caching layer, so upgrade the two packages together to get end-of-run stream deletion.
 

package/.docs/reference/pubsub/unix-socket-pubsub.md

@@ -51,4 +51,4 @@ await pubsub.close()
 
 ## Broker election
 
-The first process to bind the socket becomes the broker and routes events between all connected clients. Other processes connect as clients. When the broker exits, an exclusive lock file serializes the next election so exactly one client becomes the new broker, and the remaining clients resubscribe to it. This avoids a split-brain state where two processes both act as broker.
+The first process to bind the socket becomes the broker and routes events between all connected clients. Other processes connect as clients. When the broker exits, an exclusive lock file serializes the next election. Exactly one client becomes the new broker. The remaining clients resubscribe to it. This avoids a split-brain state where two processes both act as broker.