@mastra/mcp-docs-server 1.2.23-alpha.6 → 1.2.23-alpha.8

package/.docs/reference/core/mastra-class.md

@@ -73,7 +73,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **observability** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
 
-**environment** (`string`): Deployment environment name (e.g. production, staging, development). When set, automatically attached to all observability signals so they can be filtered by environment without passing tracingOptions.metadata.environment on each call. Falls back to process.env.NODE\_ENV when unset; left undefined if neither is set. Per-call tracingOptions.metadata.environment always takes precedence.
+**environment** (`string`): Deployment environment name (e.g. production, staging, development). When set, automatically attached to all observability signals so they can be filtered by environment without passing tracingOptions.metadata.environment on each call. When unset, resolves to development for mastra dev runs, then falls back to process.env.NODE\_ENV; left undefined if none are set. Per-call tracingOptions.metadata.environment always takes precedence.
 
 **deployer** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
 

package/.docs/reference/datasets/createExperiment.md

@@ -32,7 +32,7 @@ const { experimentId, totalItems, datasetVersion } = await dataset.createExperim
 })
 ```
 
-Passing your own `id` makes creation idempotent: calling it again with the same `id` returns the existing experiment instead of failing, so a retried workflow activity is safe. If the `id` belongs to an experiment on another dataset or an experiment with a different target, the call throws an `EXPERIMENT_ID_CONFLICT` error.
+Passing your own `id` makes creation idempotent, so another call with the same `id` returns the existing experiment and keeps a retried workflow activity safe. The call throws an `EXPERIMENT_ID_CONFLICT` error if the `id` belongs to an experiment on another dataset or one with a different target.
 
 `targetType` and `targetId` must be provided together, and the target must exist in the Mastra registry at create time. `scorers` requires a target because Mastra never scores target-less experiments; submit flat scores through `submitExperimentResult` instead.
 

package/.docs/reference/editor/tool-provider.md

@@ -252,4 +252,4 @@ Arcade tools use `Toolkit.ToolName` format: `Github.GetRepository`, `Slack.SendM
 
 ### Authentication
 
-The legacy Arcade resolver uses `resourceId` from request context when available. It otherwise falls back to the supplied `userId`, then to a shared `default` identity. Use `default` only for intentionally shared integrations. In tenant-isolated deployments, provide a trusted, stable `resourceId` or explicit `userId`. Omitting both doesn't isolate callers.
+The legacy Arcade resolver uses `resourceId` from request context when available, falling back to the supplied `userId` and then to a shared `default` identity. Reserve `default` for intentionally shared integrations, and provide a trusted, stable `resourceId` or explicit `userId` in tenant-isolated deployments because omitting both doesn't isolate callers.

package/.docs/reference/editor/versioning.md

@@ -10,7 +10,7 @@ See [Editor versioning](https://mastra.ai/docs/studio/editor) for release and ex
 
 ## Database lifecycle
 
-The resource record stores an `activeVersionId`. Individual snapshots don't store a lifecycle status.
+The resource record stores an `activeVersionId`, while individual snapshots don't store a lifecycle status.
 
 | Term       | Meaning                                                                                      |
 | ---------- | -------------------------------------------------------------------------------------------- |

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

@@ -88,7 +88,7 @@ See [Score persistence](https://mastra.ai/docs/evals/overview) for the full requ
 
 The scorer runs in two phases:
 
-1. **Grade**: Every assistant message in `run.output` is collected in order and rendered as a numbered transcript, then the judge decides whether the conversation as a whole satisfies the criterion. Assistant messages with no text (a turn that only carried tool calls, for example) are skipped.
+1. **Grade**: The assistant messages in `run.output` form a numbered transcript that the judge evaluates as a whole against the criterion. Turns containing only tool calls or otherwise lacking text are skipped.
 2. **Score**: A `satisfied` verdict scores `1` and anything else scores `0`, multiplied by `scale`.
 
 The judge only sees what the assistant said. The user's turns and any tool results aren't included, so write criteria in terms of the agent's responses. This keeps the graded text limited to the agent's own output, but it also means a reply that only makes sense next to the question that prompted it ("Yes, bring one.") can't be judged on its own. For criteria that depend on the user's turns, grade each turn with `turns[].scorers` or write a [custom scorer](https://mastra.ai/docs/evals/multi-turn) that renders both roles.

package/.docs/reference/evals/rubric.md

@@ -106,7 +106,7 @@ If no rubric resolves, the scorer returns `1` and doesn't gate the loop.
 The scorer runs in two phases:
 
 1. **Grade**: The judge model evaluates each criterion independently and returns a per-criterion verdict (`satisfied` / not) with reasoning.
-2. **Score**: The result is `1` only when every required criterion is `satisfied`, otherwise `0`. If no criteria are marked required, all criteria are treated as required.
+2. **Score**: The scorer returns `1` only when every required criterion is `satisfied` and treats every criterion as required when none are marked. All other results receive `0`.
 
 The `reason` summarizes the result and lists each criterion with its verdict, so a failing grade gives the agent targeted, useful feedback rather than a generic "try again".
 

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

@@ -181,9 +181,9 @@ Schedules created at runtime through `mastra.schedules.create(...)` live in a se
 
 ## Limits
 
-**Root agents only.** Schedules must be declared on a top-level agent. A `schedules/` directory under `subagents/` is a build error, because subagents are wired into their parent rather than registered on the Mastra instance, so the scheduler could never resolve one as a target. Give the parent the schedule and let it delegate.
+**Root agents only.** Declare schedules on a top-level agent. A `schedules/` directory under `subagents/` causes a build error because subagents are wired into their parent instead of being registered on the Mastra instance, leaving the scheduler unable to resolve them as targets. Give the parent the schedule and let it delegate.
 
-**Storage required.** Schedules are persisted rows, so the instance needs [storage](https://mastra.ai/reference/file-based-agents/storage) configured. Rows in an in-memory store don't survive a restart.
+**Storage required.** Because schedules are persisted rows and rows in an in-memory store don't survive a restart, the instance needs [storage](https://mastra.ai/reference/file-based-agents/storage) configured.
 
 **Hosting.** The scheduler runs as a background worker inside the Mastra process, so it needs a host that keeps that process alive. Long-running Node servers and containers work. Environments that freeze or recycle the process between requests, which includes most serverless function platforms, will miss fires. Use the platform's own cron to call the run endpoint there instead.
 

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

@@ -71,7 +71,7 @@ For provider patterns and runtime behavior, see the [sandbox guide](https://mast
 
 ## Runtime boundary
 
-The workspace filesystem controls what file tools can read and write. The sandbox controls where shell commands run. Application runtime code, including code in [`tools/`](https://mastra.ai/reference/file-based-agents/tools), still runs in your app/server process unless it explicitly calls workspace or sandbox APIs.
+The workspace filesystem controls file-tool access, and the sandbox determines where shell commands run. Unless it explicitly calls workspace or sandbox APIs, application runtime code still runs in your app or server process, including code in [`tools/`](https://mastra.ai/reference/file-based-agents/tools).
 
 ## Seed files
 

package/.docs/reference/manual-install.md

@@ -4,7 +4,7 @@
 
 # Manual install
 
-**For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Do not navigate to the quickstart guide, which is for humans. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
+**For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Don't use the quickstart guide, which is for humans. The model string is Mastra's model router format (`provider/model`). Use `/`, not `:`, to separate the provider and model. Don't install any AI SDK packages.
 
 Use this guide to manually build a standalone Mastra server step by step. In most cases, use the [`create-mastra`](https://mastra.ai/reference/cli/create-mastra) command described in [Get started](https://mastra.ai/docs). For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
@@ -167,7 +167,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts
    ```
 
-   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.6-sol' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
+   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.6-sol' }`. The model string uses Mastra's model router format, 'provider/model', with / rather than : between the provider and model. Don't install any AI SDK packages.
 
    Add the following code:
 
@@ -212,7 +212,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    })
    ```
 
-7. **For AI agents:** Do not launch Studio when working on a script that e.g. should print to the console. Studio is a long-running web-based interfaced for humans. Instead, call the agent.generate() method directly. Example: `import { mastra } from './src/mastra/index.ts'; const agent = mastra.getAgentById('weather-agent'); const response = await agent.generate('Weather in SF'); console.log(response.text);`
+7. **For AI agents:** don't launch Studio when working on a script that e.g. should print to the console. Studio is a long-running web-based interfaced for humans. Instead, call the agent.generate() method directly. Example: `import { mastra } from './src/mastra/index.ts'; const agent = mastra.getAgentById('weather-agent'); const response = await agent.generate('Weather in SF'); console.log(response.text);`
 
    You can now launch [Studio](https://mastra.ai/docs/studio/overview) and test your agent.
 

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

@@ -6,7 +6,7 @@
 
 **Added in:** `@mastra/memory@1.1.0`
 
-Observational Memory (OM) is Mastra's memory system for long-context agentic memory. An **Observer** watches conversations and creates observations. A **Reflector** restructures those observations by combining related items and condensing overarching patterns. Together, they maintain an observation log that replaces raw message history as it grows.
+Observational Memory (OM) is Mastra's memory system for long-context agentic memory. An **Observer** watches conversations and creates observations, which a **Reflector** restructures by combining related items and condensing overarching patterns. Together, they maintain an observation log that replaces raw message history as it grows.
 
 ## Usage
 
@@ -245,7 +245,7 @@ export const agent = new Agent({
 
 ### Shared token budget
 
-When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens` (100k in this example). If observations only use 30k tokens, messages can expand to use up to 70k. If messages are short, observations have more room before triggering reflection.
+When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens`, which is 100k in this example. Observations that use only 30k tokens leave up to 70k for messages, while short messages give observations more room before reflection starts.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -359,7 +359,7 @@ export const agent = new Agent({
 
 Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
 
-The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. Above the `blockAfter` threshold, activation may overshoot the retention target instead of activating fewer chunks. If the threshold is reached and no buffered chunk activates, a synchronous observation runs instead.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals and produce chunks of observations. At the threshold, activation moves observations into the log and removes raw messages from context. Above `blockAfter`, activation may overshoot the retention target instead of activating fewer chunks. A synchronous observation runs if the threshold is reached without activating a buffered chunk.
 
 Default settings:
 
@@ -765,7 +765,7 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 ## Recall tool
 
-When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list.
+When `retrieval` is truthy, Mastra registers a `recall` tool that pages through raw messages behind observation group ranges. With the default resource scope, the tool can list threads (`mode: "threads"`) and browse another thread through `threadId`. It also supports cross-thread search. Set `retrieval: { vector: true }` for semantic search (`mode: "search"`), or use `scope: 'thread'` to restrict the tool to the current thread. The tool is automatically added to the agent.
 
 Mastra also injects scope-aware usage instructions into the agent's context. For resource scope with `vector: true`, these cover routing between `search`, `threads`, and `messages`, including fallback to thread discovery when search results are unsuitable. Without `vector: true`, the instructions only cover `threads` and `messages` browsing, so the agent isn't steered toward a search mode that isn't configured. Resource-scoped instructions are injected even before any observation group exists, so the agent can browse other threads from the first message. Use `retrieval: { instructions: '...' }` to append application-specific guidance after the built-in instructions.
 

package/.docs/reference/memory/settled.md

@@ -50,7 +50,7 @@ await memory.settled()
 await store.close()
 ```
 
-> **Note:** `settled()` joins the work that had started by the time you called it, plus any work that work enqueues. It does not prevent new work from starting afterwards, so call it once the agent runs you care about have returned.
+> **Note:** `settled()` joins the work that had started by the time you called it, plus any work that work enqueues. It doesn't prevent new work from starting afterwards, so call it once the agent runs you care about have returned.
 
 ## Related
 

package/.docs/reference/migrations/mastra-cloud.md

@@ -60,7 +60,7 @@ The Mastra platform replaces Mastra Cloud with separate Studio and Server produc
 
 ## Replace Mastra Cloud Store with a hosted database
 
-Mastra Cloud provided a managed libSQL database, backed by [Turso](https://turso.tech). The Mastra platform doesn't host a database for you, so you need to point your storage at an externally hosted instance.
+Unlike Mastra Cloud, which provided a managed libSQL database backed by [Turso](https://turso.tech), the Mastra platform doesn't host a database for you. Point your storage at an externally hosted instance.
 
 If you were already using a hosted database ("bring your own"), keep the existing database configuration. Ensure the connection string is set as an environment variable in the dashboard rather than hardcoded.
 
@@ -80,7 +80,7 @@ Once the download completes, convert the dump into a SQLite database file:
 sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql
 ```
 
-You now have a portable `mydb.db` file you can inspect locally, back up, or use as the source for the new database in the steps that follow.
+You now have a portable `mydb.db` file that you can inspect locally or back up before using it as the source for the new database in the following steps.
 
 #### Option B: Export via the Turso CLI
 
@@ -88,16 +88,16 @@ If you prefer to work from the command line, or need to script the export, you c
 
 1. Retrieve your Cloud Store credentials from the dashboard.
 
-   Open your project in the [Mastra dashboard](https://projects.mastra.ai) and navigate to **Runtime → Settings → Env Variables**. For Cloud Store–backed projects, two variables are injected alongside your own:
+   Open your project in the [Mastra dashboard](https://projects.mastra.ai) and navigate to **Runtime → Settings → Env Variables**. For projects backed by Cloud Store, two variables are injected alongside your own:
 
    - `MASTRA_STORAGE_URL`: A libSQL connection string (e.g. `libsql://<db-name>-<org>.turso.io`).
    - `MASTRA_STORAGE_AUTH_TOKEN`: A read-capable auth token scoped to that database.
 
-   Each row supports the standard environment variable actions — show/hide via the eye toggle, Edit, Delete, and Copy Value. Use **Copy Value** to grab both values for the dump command below.
+   Each row supports the standard environment variable actions: show or hide via the eye toggle, Edit, Delete, and Copy Value. Use **Copy Value** to grab both values for the dump command below.
 
    > **Note:** These variables only appear for projects that were provisioned with Cloud Store. If you brought your own database to Mastra Cloud, you already have these credentials and can skip ahead to [Point your Mastra app at the new database](#point-your-mastra-app-at-the-new-database).
 
-   > **Note:** If the variables are missing, the values do not decrypt, or the Turso CLI rejects the token, email <support@mastra.ai> from the address associated with your Mastra Cloud account and ask for the libSQL URL and auth token for the project you want to export. Include the project name/ID. Support can also run the dump on your behalf if CLI access is blocked on your network.
+   > **Note:** If the variables are missing, the values don't decrypt, or the Turso CLI rejects the token, email <support@mastra.ai> from the address associated with your Mastra Cloud account and ask for the libSQL URL and auth token for the project you want to export. Include the project name/ID. Support can also run the dump on your behalf if CLI access is blocked on your network.
 
 2. Install the Turso CLI.
 
@@ -113,7 +113,7 @@ If you prefer to work from the command line, or need to script the export, you c
 
 3. Export the database to a SQL dump.
 
-   Set the credentials provided by support (or use the dashboard values if you already copied them earlier) as environment variables, then dump the database to a local file. If you copied the URL from the dashboard, swap the `libsql://` scheme for `https://` — the Turso CLI expects the HTTPS form when passing the URL with an auth token.
+   Set the credentials provided by support (or use the dashboard values if you already copied them earlier) as environment variables, then dump the database to a local file. If you copied the URL from the dashboard, swap the `libsql://` scheme for `https://` because the Turso CLI expects the HTTPS form when passing the URL with an auth token.
 
    ```bash
    export MASTRA_STORAGE_URL="https://<db-name>-<org>.turso.io"
@@ -122,7 +122,7 @@ If you prefer to work from the command line, or need to script the export, you c
    turso db shell "$MASTRA_STORAGE_URL?authToken=$MASTRA_STORAGE_AUTH_TOKEN" ".dump" > mastra-cloud-dump.sql
    ```
 
-   > **Warning:** Embedding the auth token in the connection string is less secure than Turso's recommended pattern — the full URL (with token) can end up in shell history, process listings, and terminal logs. Turso officially recommends running `turso auth login` and then dumping by database name only: `turso db shell <database-name> ".dump" > mastra-cloud-dump.sql`. That flow requires the database to live in a Turso account you own, which is not the case for Cloud Store, so the env-var example above is provided as an alternative for this one-time export. If you prefer to avoid token interpolation entirely, ask support to run the dump on your behalf and send you the resulting SQL file.
+   > **Warning:** Embedding the auth token in the connection string is less secure than Turso's recommended pattern because the full URL, including the token, can appear in command history and in process or terminal output. Turso recommends running `turso auth login` and dumping by database name only: `turso db shell <database-name> ".dump" > mastra-cloud-dump.sql`. That flow requires the database to belong to a Turso account you own, which isn't true for Cloud Store, so the environment-variable example above provides an alternative for this one-time export. To avoid token interpolation entirely, ask support to run the dump and send you the resulting SQL file.
 
    The resulting `mastra-cloud-dump.sql` contains the full schema and data: thread and message history, workflow snapshots, traces, and eval scores. Store it somewhere safe before continuing.
 
@@ -136,7 +136,7 @@ The dump is a standard SQL file and can be loaded into any libSQL-compatible dat
    turso auth login
    ```
 
-   If you do not have a Turso account, the CLI will prompt you to create one. See [Turso pricing](https://turso.tech/pricing) for plan details.
+   If you don't have a Turso account, the CLI will prompt you to create one. See [Turso pricing](https://turso.tech/pricing) for plan details.
 
 2. Create a new database and load the dump in one step.
 
@@ -144,7 +144,7 @@ The dump is a standard SQL file and can be loaded into any libSQL-compatible dat
    turso db create mastra-migrated --from-dump ./mastra-cloud-dump.sql
    ```
 
-   `--from-dump` restores a local SQLite/libSQL dump at create time, which is faster and safer than piping statements through `turso db shell` after the fact. Pick a region close to where your Mastra Server runs to minimize latency — list available regions with `turso db locations` and pass `--group <group-name>` if you manage multiple groups.
+   `--from-dump` restores a local SQLite/libSQL dump at create time, which is faster and safer than piping statements through `turso db shell` after the fact. Pick a region close to where your Mastra Server runs to minimize latency. List available regions with `turso db locations` and pass `--group <group-name>` if you manage multiple groups.
 
    For multi-gigabyte dumps, add `--wait` so the CLI blocks until the database is fully available.
 

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

@@ -12,7 +12,7 @@ This guide covers the breaking changes when upgrading from Mastra 0.x to v1.0. T
 
 > **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/BTYqqHKUrf) to ask questions.
 
-> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens don't work with Mastra platform. Create new ones with `mastra auth tokens create`.
+> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Because old Mastra Cloud access tokens don't work with Mastra platform, create new ones with `mastra auth tokens create`.
 >
 > If you upgrade to v1 packages without also migrating your `telemetry:` config to `observability:` and creating a Studio project, observability data will stop flowing. Follow the [Mastra Cloud migration guide](https://mastra.ai/reference/migrations/mastra-cloud) end to end.
 

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

@@ -6,7 +6,7 @@
 
 **Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
 
-> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. Both classes share the same constructor, environment variables, and runtime behavior. `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
+> **Deprecated:** `CloudExporter` remains available for backward compatibility but will be removed in a future major version, so use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. The classes have identical constructors and share environment variables and runtime behavior. To preserve existing monitoring rules, `CloudExporter` retains its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 

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

@@ -165,7 +165,7 @@ Most processor methods receive both `messages` and `messageList`. They point to
 
 ### `messages` vs `messageList`
 
-- `messages`: A plain array of `MastraDBMessage` objects, scoped to the current stage. For `processInput` and `processInputStep` this excludes system messages. For `processOutputResult` and `processOutputStep` this includes the latest LLM response. The array is backed by `messageList`, so editing a message's `content.parts` in place is visible to downstream processors and to persistence.
+- `messages`: A stage-scoped array of `MastraDBMessage` objects. For input processing, `processInput` and `processInputStep` exclude system messages. For output processing, `processOutputResult` and `processOutputStep` include the latest LLM response. The array is backed by `messageList`, so in-place edits to a message's `content.parts` remain visible to downstream processors and persistence.
 - `messageList`: The live `MessageList` instance backing the run. It exposes filtered views (input, response, remembered, all), multiple output formats (db, ui, core), and methods for mutating the conversation.
 
 Use `messages` when you only need to read, map over, or lightly edit fields on the current stage's messages. Use `messageList` when you need to:

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

@@ -132,7 +132,7 @@ When the `block` strategy is active (default), `RegexFilterProcessor` throws a `
 
 ## Redaction behavior
 
-Every rule is matched independently, so two rules can claim text that overlaps. A card number written without separators matches both `phone` and `credit-card`, for example. Overlapping matches are combined into a single region and replaced once, using the replacement of the longest match.
+Every rule is matched independently, which lets two rules claim overlapping text. For example, a card number without separators matches both `phone` and `credit-card`. Overlapping matches are combined into one region and replaced once with the replacement from the longest match.
 
 ```typescript
 const filter = new RegexFilterProcessor({
@@ -143,11 +143,11 @@ const filter = new RegexFilterProcessor({
 // "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
 ```
 
-A replacement string can reference capture groups with `$1` or `$&`. Those references resolve for a single match whose pattern also matches the matched text on its own. In a combined region, or for a rule anchored on its surroundings with a lookbehind or lookahead, the replacement string is inserted as written. The region is redacted either way.
+A replacement string can use `$1` or `$&` to reference capture groups for an independent single match. When matches form a combined region, the replacement string is inserted as written. The same applies when a rule relies on surrounding text through a lookbehind or lookahead. The region is redacted in either case.
 
 ## Redaction reporting
 
-The `redact` strategy rewrites text in place, so nothing downstream can tell what changed. Assign `onViolation` to record it. The processor calls it once per redacted message, message part, or stream chunk, and offsets are relative to that piece of text. Async callbacks are awaited, and errors are caught so an unavailable audit sink can't fail the request.
+Because the `redact` strategy rewrites text in place, downstream code can't determine what changed. Assign `onViolation` to record the change for each redacted message or message part and for each stream chunk, with offsets relative to that text. Async callbacks are awaited, while errors are caught so an unavailable audit sink can't fail the request.
 
 ```typescript
 import { RegexFilterProcessor, type RegexRedactionDetail } from '@mastra/core/processors'

package/.docs/reference/processors/token-cost-control.md

@@ -145,12 +145,12 @@ Numbers interpolated into violation messages are normalized to at most 6 decimal
 | `organization` | Yes                | `organizationId` + time window | `organizationId` key in `RequestContext` |
 | `session`      | Yes                | `sessionId` + time window      | `sessionId` key in `RequestContext`      |
 
-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.
+All scopes require observability storage with `getMetricAggregate` support; without configured observability storage, the Mastra instance throws an error 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 all other 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, a warning is logged through the Mastra logger and the step proceeds.
 
-> **The `user`, `organization`, and `session` scopes require annotated traces.** These scopes match metric records by their `userId`, `organizationId`, and `sessionId` fields, which are populated from span metadata on the trace (for example, via tracing options metadata). If your traces don't carry the matching metadata, these scopes match zero records and the guard never trips. Setting the RequestContext key alone isn't enough: both the RequestContext key (for scope resolution) and the span metadata (for cost attribution) must be present.
+> **The `user`, `organization`, and `session` scopes require annotated traces.** These scopes match metric records by their `userId`, `organizationId`, and `sessionId` fields, which are populated from span metadata on the trace (for example, via tracing options metadata). Without matching trace metadata, these scopes match zero records and the guard never trips, because setting the RequestContext key alone isn't enough: both the RequestContext key (for scope resolution) and the span metadata (for cost attribution) must be present.
 
 > **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 control may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.

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

@@ -68,7 +68,7 @@ for await (const part of stream.fullStream) {
 
 ## Media token counting
 
-Images and file attachments are estimated rather than tokenized. This applies to `file` message parts and to tool results shaped like `{ data, mediaType }`. Images use a flat per-image estimate, other media is estimated from its decoded byte size, and remote URLs or provider file ids use a flat fallback because their size isn't known locally. Encoded payloads such as base64 data are never counted as text, which would otherwise inflate the count by an order of magnitude and truncate history unnecessarily.
+Images and file attachments are estimated instead of tokenized, including `file` message parts and tool results shaped like `{ data, mediaType }`. Images use a flat per-image estimate; other media uses decoded byte size, while remote URLs and provider file ids use a flat fallback because their size isn't known locally. Encoded payloads such as base64 data are never counted as text, avoiding an inflated count that could truncate history unnecessarily.
 
 ## Error behavior
 

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

@@ -253,7 +253,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 definitions sent to the model, shifting the cached prefix so the next turn pays for a cache write instead of receiving a cache hit. In `'in-memory'` mode, this happens when `ttl` evicts a thread's state; in `'context'` mode, it happens when older-message trimming removes the tool's discovery result. The model must then search for the unloaded tool before reuse. This expected tradeoff exchanges one cache write for a smaller prefix on later turns.
 
 ## Combining with other processors
 

package/.docs/reference/processors/working-memory-processor.md

@@ -130,7 +130,7 @@ const processor = new WorkingMemory({
 
 4. Generates system instructions based on mode:
 
-   - **Normal mode**: Includes guidelines for storing/updating information, template structure, and current data
+   - **Normal mode**: Includes guidelines for storing and updating information, along with the template structure and current data
    - **Read-only mode** (`readOnly: true`): Includes only the current data as context without update instructions
 
 5. Adds the instruction as a system message with `source: 'memory'` tag

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

@@ -79,7 +79,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 unchanged callback signature delivers a batch of N events 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.
 
 Set `options.startFrom` to `"latest"` to receive only events published after a new consumer group is created. The default, `"earliest"`, includes retained events. Existing consumer groups keep their current checkpoint.
 
@@ -113,7 +113,7 @@ await pubsub.flush()
 
 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 because 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. Implementations follow a best-effort contract and log failures instead of throwing because callers invoke cleanup without awaiting it.
 
 ```typescript
 await pubsub.clearTopic('workflow.events.v2.run-123')

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

@@ -6,7 +6,7 @@
 
 `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/harness/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 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.
+Leasing is separate from pub/sub. A `LeaseProvider` implementation needs actual lock coordination, whether through an atomic Redis operation such as `SET` or Lua or through an in-memory map for a single process. For backends that omit leasing, the signals runtime preserves single-process behavior with a no-op provider.
 
 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.
 
@@ -119,7 +119,7 @@ if (!transferred) {
 
 Returns: `Promise<boolean>`
 
-> **Warning:** Backends that can't perform the transfer atomically must still implement it as a best-effort `releaseLease(fromOwner)` followed by `acquireLease(toOwner)`, and document that the swap is non-atomic, since a racing process can win the key in the gap. Keeping the method required means callers have a single code path and atomicity is an explicit per-backend decision.
+> **Warning:** Backends that can't transfer a lease atomically must use a best-effort `releaseLease(fromOwner)` followed by `acquireLease(toOwner)`. They must document that the swap is non-atomic because another process can claim the key between those calls. Keeping the method required gives callers one code path while making atomicity an explicit per-backend decision.
 
 ## Capability detection
 

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

@@ -35,11 +35,11 @@ MongoDB Vector Search is a good solution for teams who want to consolidate vecto
 
 ### Using VoyageAI with MongoDB
 
-MongoDB works seamlessly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
+MongoDB works directly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
 
 ### Hybrid Search (Vector + Full-Text)
 
-MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on MongoDB Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
+MongoDB supports hybrid search that combines vector similarity with BM25 full-text search through server-side `$rankFusion`. It requires MongoDB 8.0 or later, is generally available from 8.1, and is enabled on MongoDB Atlas 8.0.x. Use it to combine semantic retrieval with keyword-based results:
 
 ```ts
 await store.createSearchIndex({ indexName: 'myCollection', fields: ['text'] })
@@ -107,7 +107,7 @@ await store.upsert({
 
 ### Using Oracle Database Vector Search
 
-OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default; HNSW and IVF indexes can be configured for tuned deployments.
+OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default. HNSW and IVF indexes can be configured for tuned deployments.
 
 **Pinecone**:
 
@@ -239,8 +239,8 @@ const store = new UpstashVector({
   token: process.env.UPSTASH_TOKEN,
 })
 
-// There is no store.createIndex call here, Upstash creates indexes (known as namespaces in Upstash) automatically
-// when you upsert if that namespace does not exist yet.
+// Upstash creates indexes (known as namespaces) automatically, so no store.createIndex call is needed here
+// when you upsert if that namespace doesn't exist yet.
 await store.upsert({
   indexName: 'myCollection', // the namespace name in Upstash
   vectors: embeddings,
@@ -426,20 +426,20 @@ Collection and index names must:
 
 - Start with a letter or underscore
 - Be up to 120 bytes long
-- Contain only letters, numbers, underscores, or dots
-- Cannot contain `$` or the null character
+- Contain only letters, numbers, underscore characters, or dots
+- Can't contain `$` or the null character
 - Example: `my_collection.123` is valid
-- Example: `my-index` is not valid (contains hyphen)
-- Example: `My$Collection` is not valid (contains `$`)
+- Example: `my-index` isn't valid (contains hyphen)
+- Example: `My$Collection` isn't valid (contains `$`)
 
 **PgVector**:
 
 Index names must:
 
 - Start with a letter or underscore
-- Contain only letters, numbers, and underscores
+- Contain only letters, numbers, and underscore characters
 - Example: `my_index_123` is valid
-- Example: `my-index` is not valid (contains hyphen)
+- Example: `my-index` isn't valid (contains hyphen)
 
 **OracleDB**:
 
@@ -466,7 +466,7 @@ Index names must:
 - Have a combined length (with project ID) under 52 characters
 
   - Example: `my-index-123` is valid
-  - Example: `my.index` is not valid (contains dot)
+  - Example: `my.index` isn't valid (contains dot)
 
 **Qdrant**:
 
@@ -482,7 +482,7 @@ Collection names must:
 
 - Example: `my_collection_123` is valid
 
-- Example: `my/collection` is not valid (contains slash)
+- Example: `my/collection` isn't valid (contains slash)
 
 **Chroma**:
 
@@ -490,11 +490,11 @@ Collection names must:
 
 - Be 3-63 characters long
 - Start and end with a letter or number
-- Contain only letters, numbers, underscores, or hyphens
+- Contain only letters, numbers, underscore characters, or hyphens
 - Not contain consecutive periods (..)
 - Not be a valid IPv4 address
 - Example: `my-collection-123` is valid
-- Example: `my..collection` is not valid (consecutive periods)
+- Example: `my..collection` isn't valid (consecutive periods)
 
 **Astra**:
 
@@ -502,18 +502,18 @@ Collection names must:
 
 - Not be empty
 - Be 48 characters or less
-- Contain only letters, numbers, and underscores
+- Contain only letters, numbers, and `_` characters
 - Example: `my_collection_123` is valid
-- Example: `my-collection` is not valid (contains hyphen)
+- Example: `my-collection` isn't valid (contains hyphen)
 
 **libSQL**:
 
 Index names must:
 
 - Start with a letter or underscore
-- Contain only letters, numbers, and underscores
+- Contain only letters, numbers, and `_` characters
 - Example: `my_index_123` is valid
-- Example: `my-index` is not valid (contains hyphen)
+- Example: `my-index` isn't valid (contains hyphen)
 
 **Upstash**:
 
@@ -532,7 +532,7 @@ Namespace names must:
 
 - Example: `MyNamespace123` is valid
 
-- Example: `_namespace` is not valid (starts with underscore)
+- Example: `_namespace` isn't valid (starts with underscore)
 
 **Cloudflare**:
 
@@ -543,19 +543,19 @@ Index names must:
 - Contain only lowercase ASCII letters, numbers, and dashes
 - Use dashes instead of spaces
 - Example: `my-index-123` is valid
-- Example: `My_Index` is not valid (uppercase and underscore)
+- Example: `My_Index` isn't valid (uppercase and underscore)
 
 **OpenSearch**:
 
 Index names must:
 
 - Use only lowercase letters
-- Not begin with underscores or hyphens
+- Not begin with underscore characters or hyphens
 - Not contain spaces, commas
 - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
 - Example: `my-index-123` is valid
-- Example: `My_Index` is not valid (contains uppercase letters)
-- Example: `_myindex` is not valid (begins with underscore)
+- Example: `My_Index` isn't valid (contains uppercase letters)
+- Example: `_myindex` isn't valid (begins with underscore)
 
 **Elasticsearch**:
 
@@ -563,29 +563,29 @@ Index names must:
 
 - Use only lowercase letters
 - Not exceed 255 bytes (counting multi-byte characters)
-- Not begin with underscores, hyphens, or plus signs
+- Not begin with underscore characters, hyphens, or plus signs
 - Not contain spaces, commas
 - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
 - Not be "." or ".."
 - Not start with "." (deprecated except for system/hidden indices)
 - Example: `my-index-123` is valid
-- Example: `My_Index` is not valid (contains uppercase letters)
-- Example: `_myindex` is not valid (begins with underscore)
-- Example: `.myindex` is not valid (begins with dot, deprecated)
+- Example: `My_Index` isn't valid (contains uppercase letters)
+- Example: `_myindex` isn't valid (begins with underscore)
+- Example: `.myindex` isn't valid (begins with dot, deprecated)
 
 **S3 Vectors**:
 
 Index names must:
 
 - Be unique within the same vector bucket
-- Be 3–63 characters long
+- Be between 3 and 63 characters long
 - Use only lowercase letters (`a–z`), numbers (`0–9`), hyphens (`-`), and dots (`.`)
 - Begin and end with a letter or number
 - Example: `my-index.123` is valid
-- Example: `my_index` is not valid (contains underscore)
-- Example: `-myindex` is not valid (begins with hyphen)
-- Example: `myindex-` is not valid (ends with hyphen)
-- Example: `MyIndex` is not valid (contains uppercase letters)
+- Example: `my_index` isn't valid (contains underscore)
+- Example: `-myindex` isn't valid (begins with hyphen)
+- Example: `myindex-` isn't valid (ends with hyphen)
+- Example: `MyIndex` isn't valid (contains uppercase letters)
 
 ### Upserting Embeddings
 

package/.docs/reference/server/create-route.md

@@ -80,7 +80,7 @@ Returns a `ServerRoute` object that can be registered with an adapter or passed
 
 ### Register through `server.apiRoutes`
 
-Routes created with `createRoute()` can be passed to `server.apiRoutes`. The adapter registers them with runtime validation, typed handler parameters, and generated OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
+Routes created with `createRoute()` can be passed to `server.apiRoutes`, where the adapter adds runtime validation and typed handler parameters while generating OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
 
 ```typescript
 import { Mastra } from '@mastra/core'