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

package/.docs/reference/rag/chunk.md

@@ -2,7 +2,7 @@
 
 # .chunk()
 
-The `.chunk()` function splits documents into smaller segments using various strategies and options.
+The `.chunk()` function splits documents into smaller segments using strategies and options.
 
 ## Example
 
@@ -39,11 +39,11 @@ const chunksWithMetadata = await doc.chunk({
 
 ## Parameters
 
-The following parameters are available for all chunking strategies. **Important:** Each strategy will only utilize a subset of these parameters relevant to its specific use case.
+The following parameters are available for all chunking strategies. Each strategy will only utilize a subset of these parameters relevant to its specific use case.
 
 **strategy** (`'recursive' | 'character' | 'token' | 'markdown' | 'semantic-markdown' | 'html' | 'json' | 'latex' | 'sentence'`): The chunking strategy to use. If not specified, defaults based on document type. Depending on the chunking strategy, there are additional optionals. Defaults: .md files → 'markdown', .html/.htm → 'html', .json → 'json', .tex → 'latex', others → 'recursive'
 
-**maxSize** (`number`): Maximum size of each chunk. \*\*Note:\*\* Some strategy configurations (markdown with headers, HTML with headers) ignore this parameter. (Default: `4000`)
+**maxSize** (`number`): Maximum size of each chunk. Some strategy configurations (markdown with headers, HTML with headers) ignore this parameter. (Default: `4000`)
 
 **overlap** (`number`): Number of characters/tokens that overlap between chunks. (Default: `50`)
 
@@ -162,7 +162,7 @@ The options documented below are passed directly at the top level of the configu
 
 **returnEachLine** (`boolean`): Whether to return each line as a separate chunk
 
-**Important:** When using the HTML strategy, all general options are ignored. Use `headers` for header-based splitting or `sections` for section-based splitting. If used together, `sections` will be ignored.
+When using the HTML strategy, all general options are ignored. Use `headers` for header-based splitting or `sections` for section-based splitting. If used together, `sections` will be ignored.
 
 ### Markdown
 
@@ -172,7 +172,7 @@ The options documented below are passed directly at the top level of the configu
 
 **returnEachLine** (`boolean`): Whether to return each line as a separate chunk
 
-**Important:** When using the `headers` option, the markdown strategy ignores all general options and content is split based on the markdown header structure. To use size-based chunking with markdown, omit the `headers` parameter.
+When using the `headers` option, the markdown strategy ignores all general options and content is split based on the markdown header structure. To use size-based chunking with markdown, omit the `headers` parameter.
 
 ### Semantic Markdown
 

package/.docs/reference/rag/database-config.md

@@ -2,7 +2,7 @@
 
 # DatabaseConfig
 
-The `DatabaseConfig` type allows you to specify database-specific configurations when using vector query tools. These configurations enable you to leverage unique features and optimizations offered by different vector stores.
+The `DatabaseConfig` type allows you to specify database-specific configurations when using vector query tools. These configurations enable you to use features and optimizations offered by different vector stores.
 
 ## Type definition
 
@@ -252,7 +252,7 @@ const vectorTool = createVectorQueryTool({
 1. **Environment Configuration**: Use different namespaces or configurations for different environments
 2. **Performance Tuning**: Start with default values and adjust based on your specific needs
 3. **Quality Filtering**: Use minScore to filter out low-quality results
-4. **Runtime Flexibility**: Override configurations at runtime for dynamic scenarios
+4. **Runtime Flexibility**: Override configurations at runtime for runtime-defined scenarios
 5. **Documentation**: Document your specific configuration choices for team members
 
 ## Migration guide

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

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

package/.docs/reference/schedules/overview.md

@@ -150,7 +150,7 @@ const updated = await mastra.schedules.update('pinger', {
 })
 ```
 
-Agent schedule patches can update `cron`, `timezone`, `prompt`, `name`, `signalType`, `tagName`, `attributes`, `providerOptions`, `ifActive`, `ifIdle`, `metadata`, and `status`. `threadId` and `resourceId` aren't patchable; create a new schedule when the thread target needs to change.
+Agent schedule patches can update `cron`, `timezone`, `prompt`, `name`, `signalType`, `tagName`, `attributes`, `providerOptions`, `ifActive`, `ifIdle`, `metadata`, and `status`. `threadId` and `resourceId` aren't patchable. Create a new schedule when the thread target needs to change.
 
 Workflow schedule patches can update `cron`, `timezone`, `inputData`, `initialState`, `requestContext`, `metadata`, and `status`. Agent-only patch fields such as `prompt`, `signalType`, and `ifIdle` throw on workflow schedules.
 

package/.docs/reference/server/register-api-route.md

@@ -20,7 +20,7 @@ The URL path for the route. Supports path parameters using `:param` syntax.
 registerApiRoute("/items/:itemId", { ... })
 ```
 
-**Note:** Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved — for example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
+Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved. For example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
 
 ### options
 

package/.docs/reference/server/routes.md

@@ -28,7 +28,7 @@ Server adapters register these routes when you call `server.init()`. All routes
 | Parameter   | Type                     | Default   | Description                                                                                                            |
 | ----------- | ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------- |
 | `status`    | `'draft' \| 'published'` | `'draft'` | Which stored version to resolve. `draft` returns the latest version, `published` returns the active published version. |
-| `versionId` | `string`                 | —         | A specific version ID to resolve. Takes precedence over `status`.                                                      |
+| `versionId` | `string`                 | None      | A specific version ID to resolve. Takes precedence over `status`.                                                      |
 
 ```bash
 # Get agent with latest draft overrides (default)

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

@@ -51,7 +51,7 @@ const agent = new Agent({
 })
 ```
 
-The agent calls `connect(this)`, registers any processors or tools the provider returns, and starts polling.
+The agent calls `connect(this)` and registers any processors or tools the provider returns. It then starts polling.
 
 ## Constructor parameters
 
@@ -142,7 +142,7 @@ Returns: `Record<string, unknown>`
 
 #### `subscribe(target, externalResourceId, metadata?)`
 
-Subscribe a thread to an external resource. This is a protected method — call it from within your provider implementation.
+Subscribe a thread to an external resource. This is a protected method: call it from within your provider implementation.
 
 ```typescript
 const sub = this.subscribe(
@@ -152,7 +152,7 @@ const sub = this.subscribe(
 )
 ```
 
-Returns: `SignalSubscription` — the created subscription, or the existing one with merged metadata.
+Returns: `SignalSubscription`: the created subscription, or the existing one with merged metadata.
 
 **target** (`SignalProviderTarget`): The thread to subscribe. Must include threadId and resourceId.
 
@@ -171,7 +171,7 @@ const removed = this.unsubscribe(
 )
 ```
 
-Returns: `boolean` — `true` if removed, `false` if no matching subscription existed.
+Returns: `boolean`: `true` if removed, `false` if no matching subscription existed.
 
 #### `getSubscriptions()`
 
@@ -235,7 +235,7 @@ const removed = this.unsubscribeAll({
 })
 ```
 
-Returns: `number` — count of removed subscriptions.
+Returns: `number`: count of removed subscriptions.
 
 #### `subscriptionCount`
 
@@ -253,7 +253,7 @@ Returns: `number`
 
 #### `poll(subscriptions)`
 
-Called on each poll cycle with all active subscriptions. Override to check external sources and emit notifications. The framework prevents overlapping poll cycles — if a `poll()` call takes longer than `pollInterval`, the next cycle is skipped.
+Called on each poll cycle with all active subscriptions. Override to check external sources and emit notifications. The framework prevents overlapping poll cycles: if a `poll()` call takes longer than `pollInterval`, the next cycle is skipped.
 
 ```typescript
 async poll(subscriptions: SignalSubscription[]) {
@@ -271,7 +271,7 @@ async poll(subscriptions: SignalSubscription[]) {
 
 #### `startPolling()`
 
-Start the polling timer. Called by the Agent after `connect()`. Idempotent — calling multiple times has no effect.
+Start the polling timer. Called by the Agent after `connect()`. Idempotent: calling multiple times has no effect.
 
 ```typescript
 provider.startPolling()
@@ -289,7 +289,7 @@ provider.stopPolling()
 
 #### `handleWebhook(request)`
 
-Handle an incoming webhook request. Override to parse the payload, match it to subscriptions, and emit notification signals. See [`WebhookSignalProvider`](https://mastra.ai/reference/signals/webhook-signal-provider) for a ready-to-use implementation.
+Handle an incoming webhook request. Override to parse the payload and match it to subscriptions. Then emit notification signals. See [`WebhookSignalProvider`](https://mastra.ai/reference/signals/webhook-signal-provider) for a ready-to-use implementation.
 
 ```typescript
 async handleWebhook(request) {

package/.docs/reference/storage/clickhouse.md

@@ -129,7 +129,7 @@ yarn dlx mastra migrate
 bun x mastra migrate
 ```
 
-The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping, deduplicates legacy rows, and preserves the original table as a backup. After migration, traces appear in Studio through the vNext adapter.
+The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping and deduplicates legacy rows. The original table remains as a backup. After migration, traces appear in Studio through the vNext adapter.
 
 > **Note:** The legacy table isn't deleted. Drop it manually after verifying the migration.
 
@@ -261,7 +261,7 @@ Set `cluster` to add `ON CLUSTER` to Mastra-owned DDL such as table creation, ma
 
 Manual maintenance such as `optimizeTable()` and `materializeTtl()` runs on every replica when `cluster` is set. These operations can be expensive on a large cluster. Prefer running them outside peak hours, and let routine merges happen on the background merge queue rather than triggering them on every restart.
 
-If existing Mastra tables use local `MergeTree` or `ReplacingMergeTree` engines, initialization fails while `replication` is enabled. Mastra refuses to silently convert local tables because copy-and-swap is unsafe across replicas. To migrate, recreate the affected tables as `Replicated*` before enabling replication. The typical sequence is: rename the local table, run `CREATE TABLE ... ENGINE = ReplicatedMergeTree(...) ON CLUSTER ...`, run `INSERT INTO ... SELECT * FROM <renamed_local>`, then drop the renamed local table.
+If existing Mastra tables use local `MergeTree` or `ReplacingMergeTree` engines, initialization fails while `replication` is enabled. Mastra refuses to silently convert local tables because copy-and-swap is unsafe across replicas. To migrate, recreate the affected tables as `Replicated*` before enabling replication. To migrate safely, rename the local table, run `CREATE TABLE ... ENGINE = ReplicatedMergeTree(...) ON CLUSTER ...`, run `INSERT INTO ... SELECT * FROM <renamed_local>`, then drop `<renamed_local>`.
 
 Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side, and explicit `ReplicatedMergeTree` engines produce incorrect DDL. `replication` is only for self-managed multi-replica clusters.
 
@@ -271,7 +271,7 @@ Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `Shar
 
 ## Hosting options
 
-ClickHouse runs anywhere you can reach it over HTTP. Two common choices:
+ClickHouse runs anywhere you can reach it over HTTP. Common choices include:
 
 - **[ClickHouse Cloud](https://clickhouse.com/cloud)**: Managed service with a free trial tier. Provides connection details directly compatible with `url`, `username`, and `password`.
 - **Self-hosted**: Run the official [`clickhouse/clickhouse-server`](https://hub.docker.com/r/clickhouse/clickhouse-server) container or install from the [official packages](https://clickhouse.com/docs/en/install). Suitable for VPS, dedicated hardware, or Kubernetes.
@@ -333,7 +333,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Two ways to provision the database:
+Provision the database with either option:
 
 - **Managed**: Use ClickHouse Cloud. Set `CLICKHOUSE_URL`, `CLICKHOUSE_USERNAME`, and `CLICKHOUSE_PASSWORD` as environment variables in your hosting platform.
 - **Self-hosted on Railway**: Add a ClickHouse service to your Railway project from the official Docker image, then reference it in the application service through Railway's private networking.

package/.docs/reference/storage/cloudflare-d1.md

@@ -61,11 +61,11 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** When using `import { env } from 'cloudflare:workers'`, `D1Store` must be initialized inline inside `new Mastra({...})` — not extracted to a module-level variable. Alternatively, initialize `D1Store` inside the `fetch` handler after `env` is available. See [CloudflareDeployer reference](https://mastra.ai/reference/deployer/cloudflare) for details.
+> **Note:** When using `import { env } from 'cloudflare:workers'`, `D1Store` must be initialized inline inside `new Mastra({...})`: not extracted to a module-level variable. Alternatively, initialize `D1Store` inside the `fetch` handler after `env` is available. See [CloudflareDeployer reference](https://mastra.ai/reference/deployer/cloudflare) for details.
 
 ### Using in a Cloudflare Worker without HTTP routes
 
-If you want to call Mastra directly in a Worker — for example, to run an agent or trigger a workflow — without serving HTTP routes, you don't need `CloudflareDeployer`. Access the D1 binding from the worker's `env` parameter and call Mastra programmatically.
+If you want to call Mastra directly in a Worker (for example, to run an agent or trigger a workflow) without serving HTTP routes, you don't need `CloudflareDeployer`. Access the D1 binding from the worker's `env` parameter and call Mastra programmatically.
 
 ```typescript
 import { D1Store } from '@mastra/cloudflare-d1'
@@ -213,8 +213,8 @@ export default {
 
 ### Transactions & Consistency
 
-Cloudflare D1 provides transactional guarantees for single-row operations. This means that multiple operations can be executed as a single, all-or-nothing unit of work.
+Cloudflare D1 provides transactional guarantees for single-row operations. Multiple operations can be executed as a single, all-or-nothing unit of work.
 
 ### Table Creation & Migrations
 
-Tables are created automatically when storage is initialized (and can be isolated per environment using the `tablePrefix` option), but advanced schema changes—such as adding columns, changing data types, or modifying indexes—require manual migration and careful planning to avoid data loss.
+Tables are created automatically when storage is initialized (and can be isolated per environment using the `tablePrefix` option), but advanced schema changes require manual migration and careful planning. Examples include adding columns or changing data types and indexes to avoid data loss.

package/.docs/reference/storage/convex.md

@@ -182,7 +182,7 @@ During batched cleanup, cache metadata can temporarily use an internal `deleted`
 
 `clear()` only removes rows whose stored `keyPrefix` exactly matches the configured `keyPrefix`. It doesn't clear nested prefixes by string prefix matching. Each `listPush()` refreshes the list TTL using the cache's configured `ttlMs`.
 
-Use a non-empty `keyPrefix` unless you intentionally want `clear()` to remove every cache key in the deployment. Expired list rows are reclaimed incrementally during reads and writes; `clear()` removes all rows for the prefix.
+Use a non-empty `keyPrefix` unless you intentionally want `clear()` to remove every cache key in the deployment. Expired list rows are reclaimed incrementally during reads and writes. `clear()` removes all rows for the prefix.
 
 `ConvexServerCache` works best for durable replay of moderate-frequency events. For high-frequency token streams, prefer batching events or using a lower-latency cache backend.
 
@@ -217,14 +217,14 @@ All typed tables include:
 - An `id` field for Mastra's record ID (distinct from Convex's auto-generated `_id`)
 - A `by_record_id` index for efficient lookups by Mastra ID
 
-This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.
+This design ensures compatibility with Mastra's storage contract while using Convex's automatic indexing and real-time capabilities.
 
 ### Environment variables
 
 Set these environment variables for your deployment:
 
-- `CONVEX_URL` – Your Convex deployment URL
-- `CONVEX_ADMIN_KEY` – Admin authentication token (get from Convex dashboard)
+- `CONVEX_URL`: Your Convex deployment URL
+- `CONVEX_ADMIN_KEY`: Admin authentication token (get from Convex dashboard)
 
 ## Related
 

package/.docs/reference/storage/dsql.md

@@ -183,7 +183,7 @@ storage.db // Database client for executing queries
 storage.pool // Underlying pg.Pool instance
 ```
 
-This enables direct queries and custom transaction management. When using these fields:
+It supports direct queries and custom transaction management. When using these fields:
 
 - You are responsible for proper connection and transaction handling.
 - Closing the store (`storage.close()`) will destroy the connection pool if it was created by the store.
@@ -199,7 +199,7 @@ Connections are authenticated with IAM. No database passwords are required. `@ma
 
 #### Single database, schema-based isolation
 
-Each cluster exposes a single database named `postgres`. Logical separation is done via schemas. The `schemaName` option controls where Mastra tables are created.
+Each cluster exposes a single database `postgres`. Logical separation is done via schemas. The `schemaName` option controls where Mastra tables are created.
 
 #### No PostgreSQL extensions
 

package/.docs/reference/storage/dynamodb.md

@@ -2,7 +2,7 @@
 
 # DynamoDB storage
 
-The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
+The DynamoDB storage implementation provides a high-capacity and performant NoSQL database solution for Mastra, using a single-table design pattern with [ElectroDB](https://electrodb.dev/).
 
 > **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to DynamoDB, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
@@ -124,7 +124,7 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 
 ## TTL (time to live) configuration
 
-DynamoDB TTL allows you to automatically delete items after a specified time period. This is useful for:
+DynamoDB TTL allows you to automatically delete items after a specified duration for these use cases:
 
 - **Cost optimization**: Automatically remove old data to reduce storage costs
 - **Data lifecycle management**: Implement retention policies for compliance
@@ -259,19 +259,19 @@ Before diving into the architectural details, keep these key points in mind when
 
 ## Architectural approach
 
-This storage adapter utilizes a **single-table design pattern** leveraging [ElectroDB](https://electrodb.dev/), a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).
+This storage adapter utilizes a **single-table design pattern** with [ElectroDB](https://electrodb.dev/), a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).
 
 Key aspects of this approach:
 
-- **DynamoDB Native:** The single-table design is optimized for DynamoDB's key-value and query capabilities, often leading to better performance and scalability compared to mimicking relational models.
+- **DynamoDB Native:** The single-table design is optimized for DynamoDB's key-value and query capabilities, often leading to better performance and capacity compared to mimicking relational models.
 - **External Table Management:** Unlike some adapters that might offer helper functions to create tables via code, this adapter **expects the DynamoDB table and its associated Global Secondary Indexes (GSIs) to be provisioned externally** before use. Please refer to [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) for detailed instructions using tools like AWS CloudFormation or CDK. The adapter focuses solely on interacting with the pre-existing table structure.
 - **Consistency via Interface:** While the underlying storage model differs, this adapter adheres to the same `MastraStorage` interface as other adapters, ensuring it can be used interchangeably within the Mastra `Memory` component.
 
 ### Mastra Data in the Single Table
 
-Within the single DynamoDB table, different Mastra data entities (such as Threads, Messages, Traces, Evals, and Workflows) are managed and distinguished using ElectroDB. ElectroDB defines specific models for each entity type, which include unique key structures and attributes. This allows the adapter to store and retrieve diverse data types efficiently within the same table.
+Within the single DynamoDB table, different Mastra data entities (such as Threads, Messages, Traces, Evals, and Workflows) are managed and distinguished using ElectroDB. ElectroDB defines specific models for each entity type, which include unique key structures and attributes. It allows the adapter to store and retrieve diverse data types efficiently within the same table.
 
-For example, a `Thread` item might have a primary key like `THREAD#<threadId>`, while a `Message` item belonging to that thread might use `THREAD#<threadId>` as a partition key and `MESSAGE#<messageId>` as a sort key. The Global Secondary Indexes (GSIs), detailed in `TABLE_SETUP.md`, are strategically designed to support common access patterns across these different entities, such as fetching all messages for a thread or querying traces associated with a particular workflow.
+For example, a `Thread` item might have a primary key like `THREAD#<threadId>`, while a `Message` item belonging to that thread might use `THREAD#<threadId>` as a partition key and `MESSAGE#<messageId>` as a sort key. The Global Secondary Indexes (GSIs), detailed in `TABLE_SETUP.md`, are strategically designed to support common access patterns across these different entities, such as fetching all messages for a thread or querying traces associated with a workflow.
 
 ### Advantages of Single-Table Design
 
@@ -279,6 +279,6 @@ This implementation uses a single-table design pattern with ElectroDB, which off
 
 1. **Lower cost (potentially):** Fewer tables can simplify Read/Write Capacity Unit (RCU/WCU) provisioning and management, especially with on-demand capacity.
 2. **Better performance:** Related data can be co-located or accessed efficiently through GSIs, enabling fast lookups for common access patterns.
-3. **Simplified administration:** Fewer distinct tables to monitor, back up, and manage.
+3. **Simplified administration:** Fewer distinct tables to monitor and back up, with less to manage.
 4. **Reduced complexity in access patterns:** ElectroDB helps manage the complexity of item types and access patterns on a single table.
 5. **Transaction support:** DynamoDB transactions can be used across different "entity" types stored within the same table if needed.

package/.docs/reference/storage/lance.md

@@ -117,7 +117,7 @@ LanceDB storage can be configured for different deployment scenarios:
   ```text
   db://host:port
   ```
-- **S3 Storage**: Use Amazon S3 for scalable cloud storage
+- **S3 Storage**: Use Amazon S3 for high-capacity cloud storage
   ```text
   s3://bucket/db
   ```

package/.docs/reference/storage/mongodb.md

@@ -2,7 +2,7 @@
 
 # MongoDB storage
 
-The MongoDB storage implementation provides a scalable storage solution using MongoDB databases with support for both document storage and vector operations.
+The MongoDB storage implementation provides a high-capacity storage solution using MongoDB databases with support for both document storage and vector operations.
 
 ## Installation
 

package/.docs/reference/storage/mssql.md

@@ -150,7 +150,7 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 store.pool // mssql connection pool instance
 ```
 
-This enables direct queries and custom transaction management. When using these fields:
+It supports direct queries and custom transaction management. When using these fields:
 
 - You are responsible for proper connection and transaction handling.
 - Closing the store (`store.close()`) will destroy the associated connection pool.

package/.docs/reference/storage/postgresql.md

@@ -317,7 +317,7 @@ export const mastra = new Mastra({
 })
 ```
 
-This pattern ensures only one `PostgresStore` instance is created regardless of how many times the module is reloaded during development. The same pattern can be applied to other storage providers like `LibSQLStore`.
+The pattern ensures only one `PostgresStore` instance is created regardless of how many times the module is reloaded during development. The same pattern can be applied to other storage providers like `LibSQLStore`.
 
 > **Tip:** This singleton pattern is only necessary during local development with HMR. In production builds, modules are only loaded once.
 

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

@@ -4,9 +4,9 @@
 
 Storage grows without bound by default. Retention is an opt-in, age-based cleanup system: you declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Anything you don't configure is kept forever, so there is no behavior change until you opt in.
 
-`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk — on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk: on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
 
-Retention covers **growth tables** only — tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
+Retention covers **growth tables** only: tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
 The reference implementations are [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
 
@@ -31,7 +31,7 @@ const storage = new LibSQLStore({
   },
 })
 
-// Wire this to your own cron/scheduler — Mastra never runs it for you.
+// Wire this to your own cron/scheduler: Mastra never runs it for you.
 const results = await storage.prune()
 ```
 
@@ -65,35 +65,35 @@ Set the `retention` field on the store config.
 
 ### Retention-eligible tables
 
-Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data: creation time for append-only logs, last activity for live state, and completion time for jobs and runs (so in-flight work is never pruned).
-
-| Domain            | Table key          | Anchor column    | `maxAge` measures                                                 |
-| ----------------- | ------------------ | ---------------- | ----------------------------------------------------------------- |
-| `memory`          | `threads`          | `createdAt`      | Thread age                                                        |
-| `memory`          | `messages`         | `createdAt`      | Message age                                                       |
-| `memory`          | `resources`        | `createdAt`      | Resource age                                                      |
-| `threadState`     | `threadState`      | `updatedAt`      | Inactivity — state for still-active threads survives              |
-| `observability`   | `spans`            | `startedAt`      | Span age                                                          |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                    |
-| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                       |
-| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                     |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                  |
-| `scores`          | `scorers`          | `createdAt`      | Score record age                                                  |
-| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity — suspended or long-running workflows survive          |
-| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion — in-flight tasks (`NULL`) are never pruned |
-| `experiments`     | `experiments`      | `completedAt`    | Time since completion — running experiments are never pruned      |
-| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                  |
-| `harness`         | `sessions`         | `createdAt`      | Session record age                                                |
-| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                |
+Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data. Append-only logs use creation time, and live state uses last activity. Jobs and runs use completion time, so in-flight work is never pruned.
+
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                |
+| ----------------- | ------------------ | ---------------- | ---------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                       |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                      |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                         |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                   |
+| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                      |
+| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                    |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                 |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                 |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                               |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                               |
 
 > **Note:**
 >
 > - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
-> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and aren't pruned.
+> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
-> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows — effective granularity is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
+> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods
 
@@ -103,11 +103,11 @@ Each domain declares which of its tables can be age-pruned and which timestamp c
 
 Deletes rows older than their configured `maxAge` across every domain that has a policy in `retention`. Returns one `PruneResult` per table touched. With no `retention` configured it's a no-op returning `[]`.
 
-`prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks — each batch is its own transaction — so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
+`prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks (each batch is its own transaction) so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
 
-Pass `options.retention` to replace the configured policies for that call only — for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
+Pass `options.retention` to replace the configured policies for that call only: for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
 
-Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy — never at `init()` — so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build; subsequent prunes reuse the index.
+Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index.
 
 ```typescript
 const results = await storage.prune({
@@ -156,7 +156,7 @@ interface PruneResult {
 
 ## Running prune on a schedule
 
-`prune()` has no built-in scheduler — you decide when it runs. Because it's bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
+`prune()` has no built-in scheduler: you decide when it runs. Because it's bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
 
 ```typescript
 // Runs on your own cron (node-cron, a workflow schedule, an external job, etc.).
@@ -173,7 +173,7 @@ async function retentionTick() {
 }
 ```
 
-You can also cancel a long-running prune with an `AbortSignal` — the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
+You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
 
 ## MongoDB TTL indexes (alternative to prune)
 
@@ -192,7 +192,7 @@ MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/
 > - You need resumable, cancellable cleanup operations
 > - You're using composite storage with multiple databases
 >
-> Both approaches are valid. TTL is simpler; `prune()` gives more control.
+> Both approaches are valid. TTL is simpler. `prune()` gives more control.
 
 ### Setting up TTL indexes on MongoDB
 
@@ -232,9 +232,9 @@ const storage = new MongoDBStore({
 
 ## Reclaiming disk
 
-`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing — for most users this alone solves the unbounded-growth problem.
+`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing: for most users this alone solves the unbounded-growth problem.
 
-Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself, in a maintenance window — a full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
+Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
 
 For MongoDB, deleted documents are reused by future insertions. To reclaim disk space, run [`db.runCommand({ compact: "collection_name" })`](https://www.mongodb.com/docs/manual/reference/command/compact/) during a maintenance window.
 

package/.docs/reference/storage/spanner.md

@@ -2,7 +2,7 @@
 
 # Google Cloud Spanner storage
 
-The Google Cloud Spanner storage implementation provides a horizontally scalable, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.
+The Google Cloud Spanner storage implementation provides a horizontally high-capacity, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.
 
 ## Installation
 
@@ -133,14 +133,14 @@ The storage adapter creates the following tables, all using the GoogleSQL dialec
 
 Tables are created with `STRING(MAX)` for text and JSON payloads, `INT64`, `FLOAT64`, `BOOL`, and `TIMESTAMP`.
 
-Two tables also carry Spanner-specific `STORED` generated columns that the adapter populates from JSON payloads so common filters can use a regular secondary index instead of a `JSON_VALUE` scan:
+The following tables carry Spanner-specific `STORED` generated columns that the adapter populates from JSON payloads so common filters can use a regular secondary index instead of a `JSON_VALUE` scan:
 
-- `mastra_workflow_snapshot.snapshotStatus` — extracts `$.status` from `snapshot`; backs `listWorkflowRuns({ status })`.
-- `mastra_schedules.target_workflow_id` — extracts `$.workflowId` from `target`; backs `listSchedules({ workflowId })`.
+- `mastra_workflow_snapshot.snapshotStatus`: Extracts `$.status` from `snapshot`. Backs `listWorkflowRuns({ status })`.
+- `mastra_schedules.target_workflow_id`: Extracts `$.workflowId` from `target`. Backs `listSchedules({ workflowId })`.
 
 Both are added via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` during `init()` and skipped under `initMode: 'validate'` (where the schema is owned externally). When the column is absent, the adapter falls back to a `JSON_VALUE` filter at runtime.
 
-The adapter doesn't create or use named schemas; use a dedicated database for isolation.
+The adapter doesn't create or use schemas. Use a dedicated database for isolation.
 
 ### Initialization
 
@@ -184,11 +184,11 @@ const thread = await memory?.getThreadById({ threadId: '...' })
 A few behaviors differ from other relational adapters:
 
 - Upserts use `INSERT OR UPDATE`. Spanner doesn't provide a `RETURNING` clause for upserts, so callers needing the post-write state must read it back.
-- No `TRUNCATE` exists; `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
+- No `TRUNCATE` exists. `dangerouslyClearAll()` issues `DELETE WHERE TRUE`.
 - Identifiers are quoted with backticks.
 - DDL is applied through `database.updateSchema(...)`, which is asynchronous (long-running operation).
 - `NULLS FIRST/LAST` isn't supported. Ordering with NULL handling is emulated through an `IS NULL` ordering key.
-- JSON containment isn't supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan) — most one-shot lookups still work but deeply nested structural matches aren't expressible.
+- JSON containment isn't supported natively. `listTraces` `metadata` and `scope` filters compile to per-key `JSON_VALUE(...) = @v` equality checks, and `tags` filters compile to `EXISTS` over `JSON_QUERY_ARRAY(...)`. This differs from Postgres' `@>` containment operator (which can match nested structure in a single index scan): most one-shot lookups still work but deeply nested structural matches aren't expressible.
 
 ### Direct database access
 
@@ -217,4 +217,4 @@ gcloud spanner instances create test-instance --config=emulator-config --nodes=1
 gcloud spanner databases create test-db --instance=test-instance
 ```
 
-Then connect with the same env var set in your Node.js process; the `@google-cloud/spanner` client detects the emulator automatically.
+Then connect with the same env var set in your Node.js process. The `@google-cloud/spanner` client detects the emulator automatically.

package/.docs/reference/streaming/ChunkType.md

@@ -522,9 +522,9 @@ Emitted when the task throws or times out. Triggers a continuation turn when con
 
 ### background-task-suspended
 
-Emitted when a tool calls `suspend()` from inside its background execution. Pauses the task's workflow run with its snapshot persisted; resume with `mastra.backgroundTaskManager.resume(taskId, resumeData)`.
+Emitted when a tool calls `suspend()` from inside its background execution. Pauses the task's workflow run with its snapshot persisted. Resume with `mastra.backgroundTaskManager.resume(taskId, resumeData)`.
 
-When consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle), this chunk drops the task from the loop's wait set without queuing a continuation — the agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.
+When consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle), this chunk drops the task from the loop's wait set without queuing a continuation. The agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.
 
 **type** (`"background-task-suspended"`): Chunk type identifier
 

package/.docs/reference/streaming/agents/MastraModelOutput.md

@@ -2,7 +2,7 @@
 
 # MastraModelOutput
 
-The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
+The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and detailed usage tracking.
 
 ```typescript
 // MastraModelOutput is returned by agent.stream()

package/.docs/reference/streaming/agents/stream.md

@@ -2,7 +2,7 @@
 
 # Agent.stream()
 
-The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a next-generation streaming experience with support for both Mastra's native format and AI SDK v5+ compatibility.
+The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a current streaming experience with support for both Mastra's native format and AI SDK v5+ compatibility.
 
 ## Usage example