@mastra/mcp-docs-server 1.1.46-alpha.2 → 1.1.46-alpha.4

package/.docs/reference/harness/harness-class.md

@@ -166,10 +166,9 @@ const displayState = harness.getDisplayState()
 
 Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.
 
-If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.
+The task list itself is held in the thread-scoped `tasks` storage domain (the task store) and projected onto the agent state-signal lane (`stateId: "tasks"`), not in Harness state, so this method only updates the display snapshot. Task tools read and write the task store directly; you no longer need to seed `setState({ tasks })`.
 
 ```typescript
-await harness.setState({ tasks: replayedTasks })
 harness.restoreDisplayTasks(replayedTasks)
 ```
 
@@ -476,31 +475,50 @@ harness.respondToToolApproval({ decision: 'approve' })
 harness.respondToToolApproval({ decision: 'decline' })
 ```
 
-### Questions and plans
+### Tool suspensions and plans
 
-#### `respondToQuestion({ questionId, answer })`
+#### `respondToToolSuspension({ resumeData, toolCallId?, requestContext? })`
 
-Respond to a pending question from the `ask_user` built-in tool.
+Respond to a pending tool suspension. Interactive built-in tools such as `ask_user` and `request_access` pause through the native tool-suspension primitive, which emits a `tool_suspended` event carrying `toolCallId`, `toolName`, and `suspendPayload`. Pass `resumeData` to resume the suspended tool with the user's response.
+
+Provide `toolCallId` to select which suspension to resume. It is required when more than one tool is suspended at the same time (for example, parallel `ask_user` calls). When omitted, it resolves to the sole pending suspension.
 
 ```typescript
-harness.respondToQuestion({ questionId: 'q-123', answer: 'Yes, proceed with the refactor' })
+harness.subscribe(event => {
+  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
+    const { question } = event.suspendPayload as { question: string }
+    // Show `question` to the user, then resume the tool with their answer.
+    harness.respondToToolSuspension({
+      toolCallId: event.toolCallId,
+      resumeData: 'Yes, proceed with the refactor',
+    })
+  }
+})
 ```
 
 For multi-select questions, pass the selected option labels as a string array.
 
 ```typescript
-harness.respondToQuestion({ questionId: 'q-123', answer: ['Add tests', 'Update docs'] })
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: ['Add tests', 'Update docs'],
+})
 ```
 
-#### `respondToPlanApproval({ planId, response })`
+#### Responding to a submitted plan
+
+The `submit_plan` built-in tool pauses via the native tool-suspension primitive, so it surfaces through the same `tool_suspended` event as other interactive tools. Resume it with [`respondToToolSuspension`](#respondtotoolsuspension-resumedata-toolcallid-requestcontext-), passing a `resumeData` object with `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.
 
-Respond to a pending plan approval from the `submit_plan` built-in tool. The `response` object contains `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.
+On approval, the Harness automatically switches to its default (execution) mode. On rejection, the plan-mode run resumes so the agent can revise and submit again.
 
 ```typescript
-harness.respondToPlanApproval({ planId: 'plan-123', response: { action: 'approved' } })
-harness.respondToPlanApproval({
-  planId: 'plan-123',
-  response: { action: 'rejected', feedback: 'Needs more detail' },
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'approved' },
+})
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'rejected', feedback: 'Needs more detail' },
 })
 ```
 
@@ -767,7 +785,7 @@ unsubscribe()
 
 Returns: `() => void`
 
-`subscribeDisplayState()` does not call the listener immediately. Call [`getDisplayState`](#getdisplaystate) first if the UI needs an initial render before the next harness event.
+`subscribeDisplayState()` doesn't call the listener immediately. Call [`getDisplayState`](#getdisplaystate) first if the UI needs an initial render before the next harness event.
 
 #### `subscribe(listener)`
 
@@ -798,48 +816,46 @@ unsubscribe()
 
 The harness emits events through registered listeners. The following table lists the available event types:
 
-| Event type                 | Description                                                                                         |
-| -------------------------- | --------------------------------------------------------------------------------------------------- |
-| `mode_changed`             | The active mode changed.                                                                            |
-| `model_changed`            | The active model changed.                                                                           |
-| `thread_changed`           | The active thread changed.                                                                          |
-| `thread_created`           | A new thread was created.                                                                           |
-| `thread_deleted`           | A thread was deleted.                                                                               |
-| `state_changed`            | Harness state was updated.                                                                          |
-| `agent_start`              | The agent started processing.                                                                       |
-| `agent_end`                | The agent finished processing.                                                                      |
-| `message_start`            | A new message started streaming.                                                                    |
-| `message_update`           | A message was updated with new content.                                                             |
-| `message_end`              | A message finished streaming.                                                                       |
-| `tool_start`               | A tool call started.                                                                                |
-| `tool_approval_required`   | A tool call requires user approval.                                                                 |
-| `tool_update`              | A tool call was updated with progress.                                                              |
-| `tool_end`                 | A tool call finished.                                                                               |
-| `tool_input_start`         | Tool input started streaming.                                                                       |
-| `tool_input_delta`         | Tool input received a streaming delta.                                                              |
-| `tool_input_end`           | Tool input finished streaming.                                                                      |
-| `usage_update`             | Token usage was updated.                                                                            |
-| `error`                    | An error occurred.                                                                                  |
-| `info`                     | An informational message was emitted.                                                               |
-| `follow_up_queued`         | A follow-up message was queued.                                                                     |
-| `workspace_status_changed` | The workspace status changed.                                                                       |
-| `workspace_ready`          | The workspace finished initializing.                                                                |
-| `workspace_error`          | The workspace encountered an error.                                                                 |
-| `om_status`                | Observational Memory status update.                                                                 |
-| `om_observation_start`     | An observation started.                                                                             |
-| `om_observation_end`       | An observation completed.                                                                           |
-| `om_reflection_start`      | A reflection started.                                                                               |
-| `om_reflection_end`        | A reflection completed.                                                                             |
-| `ask_question`             | The agent asked a question via the `ask_user` tool. Includes optional choices and a selection mode. |
-| `plan_approval_required`   | The agent submitted a plan for approval via the `submit_plan` tool.                                 |
-| `plan_approved`            | A plan was approved.                                                                                |
-| `subagent_start`           | A subagent started processing.                                                                      |
-| `subagent_text_delta`      | A subagent emitted a text delta.                                                                    |
-| `subagent_tool_start`      | A subagent started a tool call.                                                                     |
-| `subagent_tool_end`        | A subagent finished a tool call.                                                                    |
-| `subagent_end`             | A subagent finished processing.                                                                     |
-| `subagent_model_changed`   | A subagent's model changed.                                                                         |
-| `task_updated`             | A task list was updated.                                                                            |
+| Event type                 | Description                                                                                                                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode_changed`             | The active mode changed.                                                                                                                                                                                                                                                                  |
+| `model_changed`            | The active model changed.                                                                                                                                                                                                                                                                 |
+| `thread_changed`           | The active thread changed.                                                                                                                                                                                                                                                                |
+| `thread_created`           | A new thread was created.                                                                                                                                                                                                                                                                 |
+| `thread_deleted`           | A thread was deleted.                                                                                                                                                                                                                                                                     |
+| `state_changed`            | Harness state was updated.                                                                                                                                                                                                                                                                |
+| `agent_start`              | The agent started processing.                                                                                                                                                                                                                                                             |
+| `agent_end`                | The agent finished processing.                                                                                                                                                                                                                                                            |
+| `message_start`            | A new message started streaming.                                                                                                                                                                                                                                                          |
+| `message_update`           | A message was updated with new content.                                                                                                                                                                                                                                                   |
+| `message_end`              | A message finished streaming.                                                                                                                                                                                                                                                             |
+| `tool_start`               | A tool call started.                                                                                                                                                                                                                                                                      |
+| `tool_approval_required`   | A tool call requires user approval.                                                                                                                                                                                                                                                       |
+| `tool_suspended`           | A tool paused via the native tool-suspension primitive (for example `ask_user`, `request_access`, or `submit_plan`). Includes `toolCallId`, `toolName`, and `suspendPayload`. Resume it with [`respondToToolSuspension`](#respondtotoolsuspension-resumedata-toolcallid-requestcontext-). |
+| `tool_update`              | A tool call was updated with progress.                                                                                                                                                                                                                                                    |
+| `tool_end`                 | A tool call finished.                                                                                                                                                                                                                                                                     |
+| `tool_input_start`         | Tool input started streaming.                                                                                                                                                                                                                                                             |
+| `tool_input_delta`         | Tool input received a streaming delta.                                                                                                                                                                                                                                                    |
+| `tool_input_end`           | Tool input finished streaming.                                                                                                                                                                                                                                                            |
+| `usage_update`             | Token usage was updated.                                                                                                                                                                                                                                                                  |
+| `error`                    | An error occurred.                                                                                                                                                                                                                                                                        |
+| `info`                     | An informational message was emitted.                                                                                                                                                                                                                                                     |
+| `follow_up_queued`         | A follow-up message was queued.                                                                                                                                                                                                                                                           |
+| `workspace_status_changed` | The workspace status changed.                                                                                                                                                                                                                                                             |
+| `workspace_ready`          | The workspace finished initializing.                                                                                                                                                                                                                                                      |
+| `workspace_error`          | The workspace encountered an error.                                                                                                                                                                                                                                                       |
+| `om_status`                | Observational Memory status update.                                                                                                                                                                                                                                                       |
+| `om_observation_start`     | An observation started.                                                                                                                                                                                                                                                                   |
+| `om_observation_end`       | An observation completed.                                                                                                                                                                                                                                                                 |
+| `om_reflection_start`      | A reflection started.                                                                                                                                                                                                                                                                     |
+| `om_reflection_end`        | A reflection completed.                                                                                                                                                                                                                                                                   |
+| `subagent_start`           | A subagent started processing.                                                                                                                                                                                                                                                            |
+| `subagent_text_delta`      | A subagent emitted a text delta.                                                                                                                                                                                                                                                          |
+| `subagent_tool_start`      | A subagent started a tool call.                                                                                                                                                                                                                                                           |
+| `subagent_tool_end`        | A subagent finished a tool call.                                                                                                                                                                                                                                                          |
+| `subagent_end`             | A subagent finished processing.                                                                                                                                                                                                                                                           |
+| `subagent_model_changed`   | A subagent's model changed.                                                                                                                                                                                                                                                               |
+| `task_updated`             | A task list was updated.                                                                                                                                                                                                                                                                  |
 
 ## Built-in tools
 
@@ -859,15 +875,18 @@ The harness provides built-in tools to agents in every mode:
 
 The `ask_user` tool accepts `options` for choice prompts. Set `selectionMode` to `single_select` to let the user pick one option, or `multi_select` to let the user pick multiple options. When `options` are provided and `selectionMode` is omitted, the prompt defaults to `single_select`. Omit `options` for free-text questions.
 
-The following example demonstrates a multi-select response handler. The UI reads `event.selectionMode`, lets the user choose multiple options, then returns a string array with `respondToQuestion()`.
+The following example demonstrates a multi-select response handler. The tool pauses through the `tool_suspended` event, the UI reads `selectionMode` from `event.suspendPayload`, lets the user choose multiple options, then returns a string array with `respondToToolSuspension()`.
 
 ```typescript
 harness.subscribe(event => {
-  if (event.type === 'ask_question' && event.selectionMode === 'multi_select') {
-    harness.respondToQuestion({
-      questionId: event.questionId,
-      answer: ['Add tests', 'Update docs'],
-    })
+  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
+    const { selectionMode } = event.suspendPayload as { selectionMode?: string }
+    if (selectionMode === 'multi_select') {
+      harness.respondToToolSuspension({
+        toolCallId: event.toolCallId,
+        resumeData: ['Add tests', 'Update docs'],
+      })
+    }
   }
 })
 ```

package/.docs/reference/index.md

@@ -92,6 +92,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listScorers()](https://mastra.ai/reference/core/listScorers)
 - [.listVectors()](https://mastra.ai/reference/core/listVectors)
 - [.listWorkflows()](https://mastra.ai/reference/core/listWorkflows)
+- [.removeWorkspace()](https://mastra.ai/reference/core/removeWorkspace)
 - [.setLogger()](https://mastra.ai/reference/core/setLogger)
 - [.setStorage()](https://mastra.ai/reference/core/setStorage)
 - [Cloudflare](https://mastra.ai/reference/deployer/cloudflare)
@@ -127,6 +128,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Keyword Coverage Scorer](https://mastra.ai/reference/evals/keyword-coverage)
 - [Noise Sensitivity Scorer](https://mastra.ai/reference/evals/noise-sensitivity)
 - [Prompt Alignment Scorer](https://mastra.ai/reference/evals/prompt-alignment)
+- [Rubric Scorer](https://mastra.ai/reference/evals/rubric)
 - [Textual Difference Scorer](https://mastra.ai/reference/evals/textual-difference)
 - [Tone Consistency Scorer](https://mastra.ai/reference/evals/tone-consistency)
 - [Tool Call Accuracy Scorers](https://mastra.ai/reference/evals/tool-call-accuracy)
@@ -222,6 +224,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Server Routes](https://mastra.ai/reference/server/routes)
 - [createNotificationInboxTool()](https://mastra.ai/reference/signals/create-notification-inbox-tool)
 - [SignalProvider](https://mastra.ai/reference/signals/signal-provider)
+- [TaskSignalProvider](https://mastra.ai/reference/signals/task-signal-provider)
 - [WebhookSignalProvider](https://mastra.ai/reference/signals/webhook-signal-provider)
 - [Overview](https://mastra.ai/reference/storage/overview)
 - [Aurora DSQL Storage](https://mastra.ai/reference/storage/dsql)
@@ -251,6 +254,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
+- [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
@@ -341,6 +345,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
+- [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
 - [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
 - [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)
 - [VercelMicroVMSandbox](https://mastra.ai/reference/workspace/vercel-microvm-sandbox)

package/.docs/reference/memory/serialized-memory-config.md

@@ -2,7 +2,7 @@
 
 `SerializedMemoryConfig` is the JSON-serializable subset of [`Memory`](https://mastra.ai/reference/memory/memory-class) configuration that lives on a stored agent record. The runtime hydrates it back into a `Memory` instance by resolving the vector and embedder IDs against the configured `Mastra` instance.
 
-It is the type used by [`BuilderAgentDefaults.memory`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by `EditorAgentNamespace.create({ memory })`.
+It's the type used by [`BuilderAgentDefaults.memory`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by `EditorAgentNamespace.create({ memory })`.
 
 ## Usage example
 

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

@@ -15,7 +15,7 @@ Two conditions must be true for a metric to reach storage:
 1. `MastraStorageExporter` is configured as an exporter.
 2. The storage backend supports metrics (ClickHouse or DuckDB).
 
-If metrics aren't appearing, see [troubleshooting](#troubleshooting).
+If metrics aren't available, see [troubleshooting](#troubleshooting).
 
 ## Duration metrics
 
@@ -112,11 +112,11 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 
 ## Troubleshooting
 
-### No metrics are appearing
+### No metrics are available
 
 - **Observability is configured**: Verify that your `Mastra` instance has an `observability` config with at least one exporter.
 - **`MastraStorageExporter` or `MastraPlatformExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't surface metrics in Mastra. `MastraStorageExporter` is required for the local Studio dashboard, and `MastraPlatformExporter` is required to view metrics in Mastra platform.
-- **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) are not supported for metrics.
+- **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) aren't supported for metrics.
 - **Sampling isn't 0%**: If sampling probability is `0` or strategy is `never`, all spans become no-ops and no metrics are extracted.
 
 ### Duration metrics are missing

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

@@ -121,7 +121,7 @@ new DatadogBridge({
 })
 ```
 
-Note: APM data cannot be sent in agentless mode. If you only need LLM Observability data without `dd-trace` APM, the [Datadog Exporter](https://mastra.ai/reference/observability/tracing/exporters/datadog) is a simpler choice.
+Note: APM data can't be sent in agentless mode. If you only need LLM Observability data without `dd-trace` APM, the [Datadog Exporter](https://mastra.ai/reference/observability/tracing/exporters/datadog) is a simpler choice.
 
 ### With Additional Exporters
 

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

@@ -104,7 +104,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. There is no additional filtering by metric subtype or status inside `CloudExporter`; the exporter forwards every metric event it receives unless it is 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.
 
@@ -116,7 +116,7 @@ async onScoreEvent(event: ScoreEvent): Promise<void>
 
 Processes score signals for Cloud export.
 
-Every `ScoreEvent` passed to this handler is buffered and exported to the Cloud scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.
+Every `ScoreEvent` passed to this handler is buffered and exported to the Cloud scores endpoint derived from the configured base endpoint. No extra filtering at the exporter layer beyond the disabled-exporter check is performed, so all score events received by this method are forwarded.
 
 **Returns:** `Promise<void>` after the score event has been accepted for buffering.
 
@@ -128,7 +128,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. There is no feedback-type filtering inside `CloudExporter`; 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

@@ -132,7 +132,7 @@ Failed flushes are retried with exponential backoff:
 - Maximum attempts: `maxRetries`
 - Batch is dropped after all retries fail
 
-When storage does not support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
+When storage doesn't support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
 
 ### Out-of-Order Handling
 

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

@@ -4,7 +4,7 @@
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
-> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraPlatformExporter`.
+> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it's deprecated and will be removed in a future major version. New code should use `MastraPlatformExporter`.
 
 ## Constructor
 
@@ -106,7 +106,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. There is no additional filtering by metric subtype or status inside `MastraPlatformExporter`; the exporter forwards every metric event it receives unless it is 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.
 
@@ -118,7 +118,7 @@ async onScoreEvent(event: ScoreEvent): Promise<void>
 
 Processes score signals for export.
 
-Every `ScoreEvent` passed to this handler is buffered and exported to the scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.
+Every `ScoreEvent` passed to this handler is buffered and exported to the scores endpoint derived from the configured base endpoint. No extra filtering at the exporter layer beyond the disabled-exporter check is performed, so all score events received by this method are forwarded.
 
 **Returns:** `Promise<void>` after the score event has been accepted for buffering.
 
@@ -130,7 +130,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. There is no feedback-type filtering inside `MastraPlatformExporter`; 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.
 
@@ -190,7 +190,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 is not exported from `@mastra/observability` and should not 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 & {

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

@@ -2,7 +2,7 @@
 
 Persists traces to Mastra's configured storage with automatic batching and retry logic.
 
-> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraStorageExporter`.
+> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it's deprecated and will be removed in a future major version. New code should use `MastraStorageExporter`.
 
 ## Constructor
 

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

@@ -161,7 +161,7 @@ const exporter = new OtelExporter({
 
 ## Protocol requirements
 
-Different providers require different OTEL exporter packages. Trace and log export are independent: install only the trace package if you only need traces, or install both the trace and log packages for the chosen protocol if you also want log export. Zipkin does not support OTLP logs.
+Different providers require different OTEL exporter packages. Trace and log export are independent: install only the trace package if you only need traces, or install both the trace and log packages for the chosen protocol if you also want log export. Zipkin doesn't support OTLP logs.
 
 | Protocol      | Trace package                                                 | Log package                                                  |
 | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |

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

@@ -4,7 +4,7 @@ A SpanOutputProcessor that redacts sensitive information from span fields.
 
 ## Auto-applied by default
 
-`Observability` automatically appends a `SensitiveDataFilter` to every configured instance's `spanOutputProcessors` so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You do not need to add it manually unless you want to customize its options.
+`Observability` automatically appends a `SensitiveDataFilter` to every configured instance's `spanOutputProcessors` so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You don't need to add it manually unless you want to customize its options.
 
 To opt out or customize the auto-applied filter, use the `sensitiveDataFilter` option on the [`Observability` registry config](https://mastra.ai/reference/observability/tracing/configuration):
 
@@ -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 are not 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/processors/cost-guard-processor.md

@@ -103,10 +103,10 @@ When the `block` strategy is active (default), `CostGuardProcessor` calls `abort
 | `resource` | Yes                | `resourceId` + time window  | `resourceId` in `RequestContext` |
 | `thread`   | Yes                | `threadId` + time window    | `threadId` in `RequestContext`   |
 
-All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance does not have observability storage configured, an error is thrown at registration time.
+All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance doesn't have observability storage configured, an error is thrown at registration time.
 
 For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
 
 For `resource` and `thread` scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, cost is treated as zero.
 
-> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. There is a short delay between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.
+> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. A short delay exists between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.

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

@@ -369,7 +369,7 @@ System messages are **reset to their original values** at the start of each step
 
 Processes the final LLM request after Mastra converts the `MessageList` into `LanguageModelV2Prompt` and before the provider call. Use this method for transient, model-aware rewrites that should affect only the current outbound request.
 
-Returned prompt changes are forwarded to the model for the current call only. They are not persisted back to `MessageList`, memory, UI history, or later provider calls.
+Returned prompt changes are forwarded to the model for the current call only. They're not persisted back to `MessageList`, memory, UI history, or later provider calls.
 
 ```typescript
 processLLMRequest?(
@@ -892,8 +892,8 @@ 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 cannot 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 does not leak between requests or between users.
+- **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-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.
 
 Initialize fields defensively on first access, because `state` starts as an empty object:
@@ -957,7 +957,7 @@ await writer.custom({
 })
 ```
 
-By default, processors do **not** see `data-*` chunks in `processOutputStream` so they don't accidentally process tool telemetry or their own output. Opt in by setting `processDataParts: true` on the processor:
+By default, processors **don't** see `data-*` chunks in `processOutputStream` so they don't accidentally process tool telemetry or their own output. Opt in by setting `processDataParts: true` on the processor:
 
 ```typescript
 class ModerationCollector implements Processor {

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

@@ -4,7 +4,7 @@
 
 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.
 
-There is no agent-level option for response caching; 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
 
@@ -85,7 +85,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 are instance-level concerns that should not 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
 

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

@@ -4,7 +4,7 @@ The `SkillSearchProcessor` is an **input processor** that enables on-demand skil
 
 By default, when you attach only `SkillSearchProcessor` to an agent with a skill-enabled `Workspace`, the agent treats skills as on-demand:
 
-- The default eager `SkillsProcessor` is not auto-added.
+- The default eager `SkillsProcessor` isn't auto-added.
 - `search_skills` and `load_skill` are exposed for discovery and instruction loading.
 - Overlapping `skill` and `skill_search` tools are hidden.
 - `skill_read` remains available so the agent can read supporting skill files such as references, scripts, and assets.
@@ -90,11 +90,11 @@ The agent workflow is:
 
 ## Workspace file tools
 
-`SkillSearchProcessor` loads skill instructions into the conversation. It does not block workspace file tools from reading files.
+`SkillSearchProcessor` loads skill instructions into the conversation. It doesn't block workspace file tools from reading files.
 
 Use `skill_read` for supporting files that belong to a loaded skill, such as files under `references/`, `scripts/`, or `assets/`.
 
-Reserve workspace file tools such as `mastra_workspace_read_file` for explicit file inspection or editing workflows. During normal task execution, the agent does not need to read the same `SKILL.md` file after `load_skill` succeeds.
+Reserve workspace file tools such as `mastra_workspace_read_file` for explicit file inspection or editing workflows. During normal task execution, the agent doesn't need to read the same `SKILL.md` file after `load_skill` succeeds.
 
 ## Compared to SkillsProcessor