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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.