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

package/.docs/reference/auth/auth0.md

@@ -20,7 +20,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) set. In that case, use `new MastraAuthAuth0()` without any arguments.
+> **Note:** You can omit the constructor parameters if the required environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) are set. In that case, use `new MastraAuthAuth0()` without any arguments.
 
 ## Constructor parameters
 

package/.docs/reference/auth/fga.md

@@ -61,7 +61,7 @@ Returns: `Promise<T[]>`
 
 Authorizes a non-user system actor, such as an autonomous or scheduled agent. Optional.
 
-System actors skip the user-centric `require()` path, so implement `requireActor` to enforce per-agent least privilege for them. Throw `FGADeniedError` to deny. When a provider doesn't implement `requireActor`, Mastra preserves the trusted-actor bypass (allow after the tenant-scope check), so adding it is backward compatible.
+System actors skip the user-centric `require()` path, so implement `requireActor` to enforce per-agent least privilege for them. Throw `FGADeniedError` to deny. When a provider doesn't implement `requireActor`, Mastra preserves the trusted-actor bypass (allow after the tenant-scope check), so adding the method remains backward compatible.
 
 Treat `actor.permissions` as an untrusted claim. Resolve the agent's authoritative grants from a trusted source keyed by `actor.agentId`, rather than trusting the inline values. See [System actors](https://mastra.ai/docs/server/auth/fga).
 
@@ -110,7 +110,7 @@ The `params` argument passed to `check`, `require`, and `requireActor`.
 
 ## `ActorSignal`
 
-Identifies a call made by a trusted non-user actor rather than an authenticated end user. It is either `true` (the anonymous system shorthand) or an object that names the acting agent and carries the grants a provider can enforce.
+Identifies a call made by a trusted non-user actor rather than an authenticated end user. It's either `true` (the anonymous system shorthand) or an object that names the acting agent and carries the grants a provider can enforce.
 
 **actorKind** (`'system'`): Marks the object form of the signal.
 

package/.docs/reference/auth/google.md

@@ -24,7 +24,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables set. In that case, use `new MastraAuthGoogle()` without any arguments.
+> **Note:** You can omit the constructor parameters if the required environment variables are set. In that case, use `new MastraAuthGoogle()` without any arguments.
 
 ### Constructor parameters
 
@@ -72,7 +72,7 @@ The following environment variables are automatically used when constructor opti
 
 `MastraAuthGoogle` authenticates requests in the following order:
 
-1. **Session cookie**: When SSO is enabled, reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
+1. **Session cookie.** With SSO enabled, the provider reads and decrypts the encrypted session cookie. A valid, unexpired session authenticates the user.
 2. **Google ID token fallback**: If no valid session cookie is present, verifies the `Authorization` header token against Google's JWKS endpoint.
 
 After authentication, `authorizeUser` checks that the user has a valid Google user ID, the token-derived expiration hasn't passed, and the user's verified `hd` claim matches `allowedDomains` when domains are configured.

package/.docs/reference/auth/okta.md

@@ -24,7 +24,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables set. In that case, use `new MastraAuthOkta()` without any arguments.
+> **Note:** You can omit the constructor parameters if the required environment variables are set. In that case, use `new MastraAuthOkta()` without any arguments.
 
 ### Constructor parameters
 

package/.docs/reference/auth/workos.md

@@ -20,7 +20,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`WORKOS_API_KEY` and `WORKOS_CLIENT_ID`) set. In that case, use `new MastraAuthWorkos()` without any arguments.
+> **Note:** You can omit the constructor parameters if the required environment variables (`WORKOS_API_KEY` and `WORKOS_CLIENT_ID`) are set. In that case, use `new MastraAuthWorkos()` without any arguments.
 
 ## Constructor parameters
 
@@ -56,7 +56,7 @@ By default, `MastraAuthWorkos` authorizes any authenticated WorkOS user whose re
 2. **User Retrieval**: User information is extracted from the verified token
 3. **Authorization Decision**: Access is granted if the resolved user contains the required identifiers
 
-This means that by default, `MastraAuthWorkos` acts as an authentication provider rather than a role gate.
+`MastraAuthWorkos` acts as an authentication provider rather than a role gate by default.
 
 ## FGA membership loading
 

package/.docs/reference/browser/agent-browser.md

@@ -107,7 +107,7 @@ Navigate to a URL.
 
 | Parameter   | Type                                            | Description                                     |
 | ----------- | ----------------------------------------------- | ----------------------------------------------- |
-| `url`       | `string`                                        | URL to navigate to                              |
+| `url`       | `string`                                        | URL to open                                     |
 | `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | When to consider navigation complete (optional) |
 | `timeout`   | `number`                                        | Navigation timeout in ms (optional)             |
 
@@ -358,7 +358,7 @@ Execute JavaScript in the page context. Use as an escape hatch when other tools
 
 ### `browser_screenshot`
 
-Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `browser_snapshot` when you only need text or structured data.
+Capture a screenshot of the current page as PNG (viewport by default. Set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `browser_snapshot` when you only need text or structured data.
 
 ```text
 // Viewport only (default)

package/.docs/reference/browser/browser-viewer.md

@@ -227,6 +227,6 @@ browse skills install
 
 ## Related
 
-- [BrowserViewer guide](https://mastra.ai/docs/browser/browser-viewer) — setup and usage walkthrough
-- [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser) — base class API reference
-- [Workspace overview](https://mastra.ai/docs/workspace/overview) — workspace configuration
+- [BrowserViewer guide](https://mastra.ai/docs/browser/browser-viewer): Setup and usage walkthrough
+- [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class API reference
+- [Workspace overview](https://mastra.ai/docs/workspace/overview): Workspace configuration

package/.docs/reference/browser/mastra-browser.md

@@ -2,7 +2,7 @@
 
 # MastraBrowser class
 
-The `MastraBrowser` class is the abstract base class for browser automation providers. It defines the common interface for launching browsers, managing thread isolation, streaming screencasts, and handling input events.
+The `MastraBrowser` class is the abstract base class for browser automation providers. Its common interface covers browser launch and thread isolation, plus screencast streaming and input events.
 
 You don't instantiate `MastraBrowser` directly. Instead, use a provider implementation:
 
@@ -135,7 +135,7 @@ const hasSession = browser.hasThreadSession('thread-123')
 
 #### `closeThreadSession(threadId)`
 
-Closes a specific thread's browser session. For 'thread' scope, this closes that thread's browser instance. For 'shared' scope, this clears the thread's state.
+Closes a specific thread's browser session. With 'thread' scope, it closes that thread's browser instance. With 'shared' scope, it clears the thread state.
 
 ```typescript
 await browser.closeThreadSession('thread-123')
@@ -145,7 +145,7 @@ await browser.closeThreadSession('thread-123')
 
 #### `getTools()`
 
-Returns the browser tools for use with agents. Each provider returns different tools based on its paradigm.
+Returns the browser tools for use with agents. Each provider returns different tools based on its model.
 
 ```typescript
 const tools = browser.getTools()

package/.docs/reference/browser/stagehand-browser.md

@@ -79,7 +79,7 @@ Core tools:
 | ---------------------- | ------------------------------------------------------------------------------------- |
 | `stagehand_act`        | Perform actions using natural language instructions                                   |
 | `stagehand_extract`    | Extract structured data from pages                                                    |
-| `stagehand_observe`    | Discover actionable elements on a page                                                |
+| `stagehand_observe`    | Discover useful elements on a page                                                    |
 | `stagehand_navigate`   | Navigate to a URL                                                                     |
 | `stagehand_tabs`       | Manage browser tabs                                                                   |
 | `stagehand_screenshot` | Capture a screenshot as PNG (viewport by default; set `fullPage: true` for full page) |
@@ -171,7 +171,7 @@ interface ExtractResult<T = unknown> {
 
 ### `stagehand_observe`
 
-Discover actionable elements on a page. Returns a list of elements with their selectors and descriptions.
+Discover useful elements on a page. Returns a list of elements with their selectors and descriptions.
 
 ```text
 // Find specific elements
@@ -222,7 +222,7 @@ Navigate to a URL.
 
 | Parameter   | Type                                            | Description                                     |
 | ----------- | ----------------------------------------------- | ----------------------------------------------- |
-| `url`       | `string`                                        | URL to navigate to (required)                   |
+| `url`       | `string`                                        | URL to open (required)                          |
 | `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | When to consider navigation complete (optional) |
 
 ### `stagehand_tabs`
@@ -245,7 +245,7 @@ Manage browser tabs.
 
 ### `stagehand_screenshot`
 
-Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `stagehand_observe` or `stagehand_extract` when you only need text or structured data.
+Capture a screenshot of the current page as PNG (viewport by default. Set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `stagehand_observe` or `stagehand_extract` when you only need text or structured data.
 
 ```text
 // Viewport only (default)

package/.docs/reference/channels/slack-provider.md

@@ -6,7 +6,7 @@
 
 ## Usage example
 
-Register the provider on the `Mastra` constructor. The refresh token is single-use and rotates on startup; the resulting access tokens are persisted to `Mastra.storage`.
+Register the provider on the `Mastra` constructor. The refresh token is single-use and rotates on startup. The resulting access tokens are persisted to `Mastra.storage`.
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
@@ -171,7 +171,7 @@ slack.setBaseUrl('https://abc123.trycloudflare.com')
 
 #### `initialize()`
 
-Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Doesn't auto-provision new apps; use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
+Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Doesn't auto-provision new apps. Use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
 
 ```typescript
 await slack.initialize()

package/.docs/reference/cli/create-mastra.md

@@ -60,7 +60,7 @@ yarn dlx create-mastra@latest my-mastra-project --llm anthropic
 bun x create-mastra@latest my-mastra-project --llm anthropic
 ```
 
-Omit `--llm` to select the provider and optionally enter its API key interactively. The interactive setup also offers to connect your project to the Mastra platform. If enabled, the command opens the browser authentication flow, creates a platform project with the same name as the local project, and writes `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`.
+Omit `--llm` to select the provider and optionally enter its API key interactively. The interactive setup also offers to connect your project to the Mastra platform. If enabled, the command opens the browser authentication flow and creates a platform project with the same name as the local project. It then writes `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`.
 
 ### Template
 

package/.docs/reference/cli/mastra.md

@@ -32,7 +32,7 @@ Comma-separated list of custom arguments to pass to the Node.js process, e.g. `-
 
 #### `--request-context-presets`
 
-Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. When provided, a dropdown displays in Studio's request context editor, letting you quickly switch between preset configurations.
+Path to a JSON file containing [request context](https://mastra.ai/docs/server/request-context) presets. When provided, a dropdown displays in Studio's request context editor, letting you quickly switch between preset configurations.
 
 ```bash
 mastra dev --request-context-presets ./presets.json
@@ -49,7 +49,7 @@ The file must be a JSON object where each key is a preset name and each value is
 
 ### Configs
 
-You can set certain environment variables to modify the behavior of `mastra dev`.
+You can set environment variables to modify the behavior of `mastra dev`.
 
 #### Skip peer dependency check
 
@@ -121,7 +121,7 @@ Under the hood Mastra's Rollup server locates your Mastra entry file and bundles
 
 The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
 
-If you're deploying to a [serverless platform](https://mastra.ai/docs/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform](https://mastra.ai/docs/deployment/cloud-providers) you need to install the correct deployer to receive the correct output in `.mastra`.
 
 It accepts [common flags](#common-flags).
 
@@ -133,7 +133,7 @@ Bundle the Studio UI with the build.
 
 ### Configs
 
-You can set certain environment variables to modify the behavior of `mastra build`.
+You can set environment variables to modify the behavior of `mastra build`.
 
 #### Skip peer dependency check
 
@@ -199,7 +199,7 @@ The API route prefix of the Mastra API server. Defaults to `/api`.
 
 #### `--request-context-presets`
 
-Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).
+Path to a JSON file containing [request context](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).
 
 ```bash
 mastra studio --request-context-presets ./presets.json
@@ -207,7 +207,7 @@ mastra studio --request-context-presets ./presets.json
 
 ## `mastra deploy`
 
-Builds and deploys your project to a named environment on Mastra platform. This is the recommended command for all new deploys and replaces both [`mastra studio deploy`](#mastra-studio-deploy) and [`mastra server deploy`](#mastra-server-deploy), which continue to work but should no longer be used for new setups.
+Builds and deploys your project to the Mastra platform environment selected by `--env`. This is the recommended command for all new deploys and replaces both [`mastra studio deploy`](#mastra-studio-deploy) and [`mastra server deploy`](#mastra-server-deploy), which continue to work but should no longer be used for new setups.
 
 Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.
 
@@ -217,7 +217,7 @@ mastra deploy --env staging
 mastra deploy --env production --region eu
 ```
 
-The command runs `mastra build`, zips the output, uploads it to the selected environment, and then polls the deploy status while streaming build logs until the deploy reaches a terminal state.
+The command runs `mastra build` and zips the output before uploading it to the selected environment. It then polls the deploy status while streaming build logs until the deploy reaches a terminal state.
 
 Organization, project, and environment are resolved in order from: environment variable (`MASTRA_ORG_ID`, `MASTRA_PROJECT_ID`), CLI flag (`--org`, `--project`, `--env`), `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved org and project IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
 
@@ -294,9 +294,9 @@ mastra deploy --env staging --yes
 
 ## `mastra env`
 
-Manages environments on Mastra platform. Environments are named deploy targets (for example `production`, `staging`, `preview-42`) that belong to a project. The current organization is resolved from stored credentials.
+Manages environments on Mastra platform. Environments are deploy targets (for example `production`, `staging`, `preview-42`) that belong to a project. The current organization is resolved from stored credentials.
 
-Every subcommand resolves its project from, in order: the `MASTRA_PROJECT_ID` environment variable, the `--project <name|slug|id>` flag, or the `.mastra-project.json` file written by [`mastra deploy`](#mastra-deploy) in the current directory. Run from your project directory and you never need to name the project.
+Every subcommand resolves its project in a fixed order. It first checks the `MASTRA_PROJECT_ID` environment variable and the `--project <name|slug|id>` flag. It then reads the `.mastra-project.json` file written by [`mastra deploy`](#mastra-deploy) in the current directory. Run from your project directory and you never need to name the project.
 
 ### `mastra env list`
 
@@ -356,7 +356,7 @@ mastra env restart <env>
 
 ### `mastra env vars pull`
 
-Pulls an environment's env vars into a local env file (default: `.env`). The file contains the merged set a deploy actually runs with: vars stored on the environment (for example, added in the dashboard's environment editor) plus project-level vars, with project values winning on conflict. Managed vars injected by attached databases are listed as comments (names only) since their values are platform-managed secrets.
+Pulls an environment's env vars into a local env file (default: `.env`). The file contains the merged set used by a deploy. It combines vars stored on the environment (for example, added in the dashboard's environment editor) with project-level vars. Project values win on conflict. Managed vars injected by attached databases are listed as comments (names only) since their values are platform-managed secrets.
 
 ```bash
 mastra env vars pull
@@ -373,7 +373,7 @@ File to write. Defaults to `.env`.
 
 Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.
 
-A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Environment-scoped is the default for `mastra env db create` — pass an environment argument, or let the CLI pick or prompt for one. Pass `--shared` on create to attach a shared database instead. For other subcommands (`list`, `delete`, `keys`), pass the environment argument to work with environment-scoped databases and omit it for shared databases.
+A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Environment-scoped is the default for `mastra env db create`: pass an environment argument, or let the CLI pick or prompt for one. Pass `--shared` on create to attach a shared database instead. For other subcommands (`list`, `delete`, `keys`), pass the environment argument to work with environment-scoped databases and omit it for shared databases.
 
 Creating and deleting databases requires the `admin` role in the organization.
 
@@ -392,7 +392,7 @@ Emit machine-readable JSON.
 
 ### `mastra env db create`
 
-Provisions a managed database, attaches it, and polls until it's ready. Provisioning errors are printed with the provider's error detail.
+Provisions and attaches a managed database, then polls until it's ready. Provisioning errors are printed with the provider's error detail.
 
 By default the database is scoped to a single environment: pass an environment argument to pick it, or omit the argument to have the CLI pick for you. When the project has one environment, that environment is used. When it has several, the CLI prompts you to select one interactively; in non-interactive contexts (CI, `--json`) an environment argument is required. Pass `--shared` to attach a project-scoped database that's shared by every environment instead.
 
@@ -419,7 +419,7 @@ Provider region ID for shared databases. Ignored for environment-scoped database
 
 #### `--shared`
 
-Attach as a project-scoped database that's shared by every environment. Cannot be combined with an environment argument.
+Attach as a project-scoped database that's shared by every environment. Can't be combined with an environment argument.
 
 #### `--no-wait`
 
@@ -475,7 +475,7 @@ Emit machine-readable JSON.
 
 ## `mastra studio deploy`
 
-> **Info:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports named environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
+> **Info:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
 
 Builds and deploys your project to Mastra platform. Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.
 
@@ -483,11 +483,11 @@ Builds and deploys your project to Mastra platform. Requires authentication via
 mastra studio deploy
 ```
 
-The command runs `mastra build`, zips the output, reads an env file from the project directory, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
+The command runs `mastra build` and zips the output. It reads an env file from the project directory before uploading everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
 
 The deploy command auto-loads the project's `.env` file. If `MASTRA_PROJECT_ID` points to a project that was provisioned for Observability, the deploy links to that project instead of creating a new one. Deploying Studio to an observability-only project converts it into a Studio project on the platform side.
 
-The CLI requires at least one `.env` or `.env.*` file (excluding `.env.example`) in the project directory and fails with `Error: No env file found for deploy.` if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to `.env.production`); pass `--env-file` to choose explicitly. With `--yes` and multiple env files, you must pass `--env-file` or the deploy errors.
+The CLI requires at least one `.env` or `.env.*` file (excluding `.env.example`) in the project directory and fails with `Error: No env file found for deploy.` if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to `.env.production`). Pass `--env-file` to choose explicitly. With `--yes` and multiple env files, you must pass `--env-file` or the deploy errors.
 
 Organization and project are resolved in order from: Environment variable flag, `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
 
@@ -581,7 +581,7 @@ Shows diagnosis results and suggested fixes for a failed Studio deploy.
 mastra studio deploy suggestions [deploy-id]
 ```
 
-If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. Suggestions appear only when the diagnosis finds a problem.
 
 ### `mastra studio projects`
 
@@ -593,7 +593,7 @@ Creates a new project through an interactive prompt. This command doesn't accept
 
 ## `mastra server deploy`
 
-> **Info:** `mastra server deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which deploys a single project to multiple named environments instead of separate Studio and Server commands. New setups should use `mastra deploy`.
+> **Info:** `mastra server deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which deploys a single project to multiple environments instead of separate Studio and Server commands. New setups should use `mastra deploy`.
 
 Builds and deploys your project to Server on Mastra platform. Works the same as [`mastra studio deploy`](#mastra-studio-deploy) with the same flags, arguments, and resolution logic.
 
@@ -611,7 +611,7 @@ Shows diagnosis results and suggested fixes for a failed Server deploy.
 mastra server deploy suggestions [deploy-id]
 ```
 
-If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. Suggestions appear only when the diagnosis finds a problem.
 
 ## `mastra server pause`
 
@@ -649,7 +649,7 @@ Same flags as [`mastra server pause`](#mastra-server-pause): **`--org`**, **`--p
 mastra server restart
 ```
 
-Fails if a deployment is still active for this project (running, building, deploying, etc.); that's a platform restriction so you can't restart while another deploy is in progress.
+Fails if a deployment is still active for this project (running, building, deploying, etc.). That's a platform restriction so you can't restart while another deploy is in progress.
 
 ## `mastra server env`
 
@@ -892,7 +892,7 @@ Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "c
 
 #### `--observability`
 
-Enable Observability on the Mastra platform. The CLI prompts you to select an existing platform project or create a new one, writes the required environment variables, and configures the observability exporters.
+Enable Observability on the Mastra platform. The CLI prompts you to select an existing platform project or create a new one. It then writes the required environment variables and configures the observability exporters.
 
 #### `--no-observability`
 
@@ -906,7 +906,7 @@ Set the platform project name to use when Mastra Observability is enabled.
 
 Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.
 
-The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
+The command bundles your project and connects to your configured storage backend. It then executes any pending migrations. Currently supports:
 
 - **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
 - **ClickHouse legacy-to-vNext span migration**: Copies historical spans from the legacy `mastra_ai_spans` table to the vNext `mastra_span_events` schema. Runs in batches to stay within memory limits. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
@@ -1417,7 +1417,7 @@ curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/sp
 
 #### `mastra api score create`
 
-Creates an observability score. The input uses the server score body shape; inspect it with `--schema`.
+Creates an observability score. The input uses the server score body shape. Inspect it with `--schema`.
 
 ```bash
 mastra api score create <input>

package/.docs/reference/client-js/agents.md

@@ -2,7 +2,7 @@
 
 # Agents API
 
-The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
+The Agents API provides methods to interact with Mastra AI agents, including generating responses and streaming interactions. It also provides methods for managing agent tools.
 
 ## Getting all agents
 
@@ -155,7 +155,7 @@ for await (const part of uiMessageStream) {
 
 ### `sendMessage()`
 
-Send user-authored input to an active agent run or idle memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the message.
+Send user-authored input to an active agent run or idle memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives the message.
 
 ```typescript
 const agent = mastraClient.getAgent('support-agent')
@@ -285,7 +285,7 @@ await subscription.processDataStream({
 
 ### `streamUntilIdle()`
 
-Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
+Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `stream()`.
 
 ```typescript
 const response = await agent.streamUntilIdle('Research solana for me', {
@@ -307,7 +307,7 @@ response.processDataStream({
 
 ### `resumeStreamUntilIdle()`
 
-Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `resumeStream()`:
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `resumeStream()`:
 
 ```typescript
 const response = await agent.resumeStreamUntilIdle(
@@ -366,7 +366,7 @@ response.processDataStream({
 
 ### `listSuspendedRuns()`
 
-List suspended runs for the agent from storage — runs waiting on a tool-call approval or on a tool that suspended. Discovery is backed by storage, so it works after a server restart and across server instances. Pass the returned `runId` to `approveToolCall()`, `declineToolCall()`, or `resumeStream()`.
+List suspended runs for the agent from storage: runs waiting on a tool-call approval or on a tool that suspended. Discovery is backed by storage, so it works after a server restart and across server instances. Pass the returned `runId` to `approveToolCall()`, `declineToolCall()`, or `resumeStream()`.
 
 ```typescript
 const { runs, total } = await agent.listSuspendedRuns({
@@ -655,9 +655,9 @@ const screenshotTool = createTool({
 
 ### Tracing client tools
 
-When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call, injects a W3C trace carrier into the outgoing tool-call chunk, and ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.
+When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call and injects a W3C trace carrier into the outgoing tool-call chunk. It ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.
 
-The client SDK also measures the wall-clock duration of each client tool's `execute` function and ships it back to the server, where it's emitted as a `mastra_tool_duration_ms` metric with `toolType: "client"`.
+The client SDK also measures the wall-clock duration of each client tool's `execute` function and sends it back to the server, where it's emitted as a `mastra_tool_duration_ms` metric with `toolType: "client"`.
 
 For richer telemetry from inside your tool's `execute` function, use the `observe` helper on the execution context to add child spans and structured logs:
 
@@ -680,9 +680,9 @@ const fetchUserTool = createTool({
 })
 ```
 
-`observe` is always available — when no tracing context is active (e.g. running outside a traced agent), `span` runs the function directly and `log` is a no-op. No null-checking needed.
+`observe` is always available: when no tracing context is active (e.g. running outside a traced agent), `span` runs the function directly and `log` is a no-op. No null-checking needed.
 
-The SDK serializes everything the collector buffered as OTLP/JSON and ships it back in the next request body. The server's `@mastra/observability` package validates that the spans belong to the correct trace (preventing cross-trace injection) and forwards each span/log into the same observability bus that server-side telemetry uses. Your existing exporters pick them up automatically after observability is configured.
+The SDK serializes everything the collector buffered as OTLP/JSON and sends it back in the next request body. The server's `@mastra/observability` package validates that the spans belong to the correct trace (preventing cross-trace injection) and forwards each span/log into the same observability bus that server-side telemetry uses. Your existing exporters pick them up automatically after observability is configured.
 
 ## Stored agents
 

package/.docs/reference/client-js/memory.md

@@ -168,7 +168,7 @@ const result = await thread.listMessages({
 })
 ```
 
-Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. Every key-value pair must match with AND semantics. `null` matches an explicit `null` value, not a missing metadata key. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the server storage backend, and arbitrary metadata filters may scan candidate messages.
+Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. Every key-value pair must match with AND semantics. `null` matches only keys explicitly set to `null`. Metadata keys must start with a letter or underscore and contain only alphanumeric or underscore characters. The limit is 128 characters. Reserved prototype keys such as `__proto__`, `constructor`, and `prototype` aren't allowed. Performance depends on the server storage backend, and arbitrary metadata filters may scan candidate messages.
 
 ### Delete Messages
 
@@ -226,7 +226,7 @@ await mastraClient.updateWorkingMemory({
 // Returns: { success: true }
 ```
 
-**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+For resource-scoped working memory, you must provide the `resourceId` parameter. It allows the memory to persist across all conversation threads for that user.
 
 ### Get Memory Status
 

package/.docs/reference/client-js/workflows.md

@@ -142,7 +142,7 @@ await run.resume({
 })
 ```
 
-When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based; `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
+When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based. `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
 
 ```typescript
 await run.resume({

package/.docs/reference/coding-agent/build-base-prompt.md

@@ -2,11 +2,11 @@
 
 # buildBasePrompt()
 
-`buildBasePrompt()` builds the shared base system prompt for a coding agent — the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
+`buildBasePrompt()` builds the shared base system prompt for a coding agent: the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
 
 Product-specific strings are parameterized through `productName`, `coAuthorName`, and `coAuthorEmail`, so you can rebrand the prompt and commit trailer without forking it. They default to `"Mastra Code"` / `"noreply@mastra.ai"`, so existing callers keep identical output.
 
-Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build dynamic instructions for the agent.
+Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build runtime-defined instructions for the agent.
 
 ## Usage example
 

package/.docs/reference/coding-agent/create-coding-agent.md

@@ -4,7 +4,7 @@
 
 `createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only `model`, `instructions`, and `tools` to get a working agent, or override any default.
 
-The returned value is a standard `Agent`, so it works anywhere an `Agent` does — including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+The returned value is a standard `Agent`, so it works anywhere an `Agent` does: including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 ## Usage example
 
@@ -70,7 +70,7 @@ new Workspace({
 })
 ```
 
-To opt out — for example when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level — pass `workspace: undefined` explicitly:
+To opt out (for example, when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level), pass `workspace: undefined` explicitly:
 
 ```typescript
 const agent = createCodingAgent({

package/.docs/reference/configuration.md

@@ -242,7 +242,7 @@ export const mastra = new Mastra({
 
 **Type:** `Record<string, MastraMemory>`
 
-A registry of memory instances that can be referenced by agents. Memory gives agents coherence across interactions by retaining relevant information from past conversations. Mastra supports three types of memory: message history for recent messages, working memory for persistent user-specific details, and semantic recall for retrieving older messages based on relevance.
+A registry of memory instances that can be referenced by agents. Memory gives agents coherence across interactions by retaining relevant information from past conversations. Mastra supports message history for recent messages and working memory for persistent user-specific details. Semantic recall retrieves older messages based on relevance.
 
 Visit the [Memory documentation](https://mastra.ai/docs/memory/overview) to learn more.
 
@@ -343,7 +343,7 @@ export const mastra = new Mastra({
 
 **Type:** `Record<string, Scorer>`
 
-Scorers assess the quality of agent responses and workflow outputs. They provide quantifiable metrics for measuring agent quality using model-graded, rule-based, and statistical methods. Use scorers to track performance, compare approaches, and identify areas for improvement.
+Scorers assess the quality of agent responses and workflow outputs. They provide quantifiable metrics for measuring agent quality using model-graded, rule-based, and statistical methods. Use scorers to track performance and compare approaches. They can also identify areas for improvement.
 
 Visit the [Scorers documentation](https://mastra.ai/docs/evals/overview) to learn more.
 
@@ -505,11 +505,11 @@ const mastra = new Mastra({
 **Type:** `boolean | string[]`\
 **Default:** `true`
 
-When `mastra build` is run, Mastra bundles your project into the `.mastra/output` directory. This option controls which packages are excluded from the bundle (marked as "external") and installed separately through a package manager. This is useful when the internal Mastra bundler ([Rollup](https://rollupjs.org/configuration-options/#external)) has trouble bundling certain packages.
+When `mastra build` is run, Mastra bundles your project into the `.mastra/output` directory. This option controls which packages are excluded from the bundle (marked as "external") and installed separately through a package manager. This is useful when the internal Mastra bundler ([Rollup](https://rollupjs.org/configuration-options/#external)) has trouble bundling packages.
 
 By default, `mastra build` sets this option to `true`.
 
-Here's an overview of what the different values mean:
+The values have these meanings:
 
 - `true`: All dependencies listed in your project's `package.json` are marked as external
 - `false`: No dependencies are marked as external; everything is bundled together
@@ -784,7 +784,7 @@ export const mastra = new Mastra({
 
 Custom error handler called when an unhandled error occurs. Use this to customize error responses, log errors to external services like Sentry, or implement custom error formatting.
 
-This hook is supported by all server adapters. The `c` parameter provides a Hono-compatible context object — for non-Hono adapters (Koa, Express, Fastify), a shim is provided with commonly used methods like `c.json()` and `c.req.path`.
+This hook is supported by all server adapters. The `c` parameter provides a Hono-compatible context object: for non-Hono adapters (Koa, Express, Fastify), a shim is provided with commonly used methods like `c.json()` and `c.req.path`.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -813,7 +813,7 @@ export const mastra = new Mastra({
 
 Custom handler called when a request fails Zod schema validation. Use this to customize validation error responses, change the status code, or format errors to match your API standards.
 
-Return a `{ status, body }` object to override the default `400` response, or `undefined` to fall through to the default behavior. This hook is supported by all server adapters (Hono, Express, Fastify, Koa).
+Return a `{ status, body }` object to override the default `400` response, or `undefined` to use the default behavior. This hook is supported by all server adapters (Hono, Express, Fastify, Koa).
 
 The `context` parameter indicates which part of the request failed validation:
 

package/.docs/reference/core/getMCPServer.md

@@ -30,7 +30,7 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
 
 ## Parameters
 
-**registryKey** (`string`): The registry key used when registering the MCP server in the mcpServers configuration object. This is the key in the key-value pair, not the server's intrinsic id property.
+**registryKey** (`string`): The registry key used when registering the MCP server in the mcpServers configuration object. It is the configuration key in the key-value pair, not the server's intrinsic id property.
 
 ## Returns
 

package/.docs/reference/core/getScorer.md

@@ -2,7 +2,7 @@
 
 # getScorer()
 
-The `getScorer()` method retrieves a specific scorer that was registered with the Mastra instance using its registration key. This method provides type-safe access to scorers and throws an error if the requested scorer isn't found.
+The `getScorer()` method retrieves a specific scorer that was registered with the Mastra instance using its registration key. The method provides type-safe access to scorers and throws an error if the requested scorer isn't found.
 
 ## Usage example