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

package/.docs/reference/agents/getDefaultOptions.md

@@ -2,7 +2,7 @@
 
 # Agent.getDefaultOptions()
 
-Agents can be configured with default options for memory usage, output format, and iteration steps. The `.getDefaultOptions()` method returns these defaults, resolving them if they're functions. These options apply to all `stream()` and `generate()` calls unless overridden and are useful for inspecting an agent’s unknown defaults.
+Agents can be configured with default options for memory usage and output format. Iteration steps can also be configured. The `.getDefaultOptions()` method returns these defaults, resolving them if they're functions. These options apply to all `stream()` and `generate()` calls unless overridden and are useful for inspecting an agent’s unknown defaults.
 
 ## Usage example
 

package/.docs/reference/agents/getDefaultStreamOptions.md

@@ -4,7 +4,7 @@
 
 > **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.getDefaultOptions()`](https://mastra.ai/reference/agents/getDefaultOptions) method instead.
 
-Agents can be configured with default streaming options for memory usage, output format, and iteration steps. The `.getDefaultStreamOptionsLegacy()` method returns these defaults, resolving them if they're functions. These options apply to all `streamLegacy()` calls unless overridden and are useful for inspecting an agent’s unknown defaults.
+Agents can be configured with default streaming options for memory usage and output format. Iteration steps can also be configured. The `.getDefaultStreamOptionsLegacy()` method returns these defaults, resolving them if they're functions. These options apply to all `streamLegacy()` calls unless overridden and are useful for inspecting an agent’s unknown defaults.
 
 ## Usage example
 

package/.docs/reference/agents/listScorers.md

@@ -2,7 +2,7 @@
 
 # Agent.listScorers()
 
-The `.listScorers()` method retrieves the scoring configuration configured for an agent, resolving it if it's a function. This method provides access to the scoring system used for evaluating agent responses and performance.
+The `.listScorers()` method retrieves the scoring configuration configured for an agent, resolving it if it's a function. The method provides access to the scoring system used for evaluating agent responses and performance.
 
 ## Usage example
 

package/.docs/reference/agents/listSkills.md

@@ -46,7 +46,7 @@ interface SkillMetadata {
 
 ## Merging behavior
 
-When both agent-level skills and workspace skills are configured, `.listSkills()` returns the merged set. Agent-level skills take precedence on name conflicts — if both define a skill named `code-review`, only the agent-level version is returned.
+When both agent-level skills and workspace skills are configured, `.listSkills()` returns the merged set. Agent-level skills take precedence on name conflicts. If both define a skill called `code-review`, only the agent-level version is returned.
 
 ## Related
 

package/.docs/reference/agents/listSuspendedRuns.md

@@ -12,7 +12,7 @@ The filter contract mirrors the workflow run listing APIs (`listWorkflowRuns`),
 
 ## Usage example
 
-Discover the pending run for a conversation and continue it. Check `requiresApproval` to pick the right continuation — `approveToolCall()` / `declineToolCall()` for approval suspensions, `resumeStream()` with resume data for `suspend()`-based suspensions:
+Discover the pending run for a conversation and continue it. Check `requiresApproval` to pick the right continuation: `approveToolCall()` / `declineToolCall()` for approval suspensions, `resumeStream()` with resume data for `suspend()`-based suspensions:
 
 ```typescript
 const { runs } = await agent.listSuspendedRuns({
@@ -83,7 +83,7 @@ interface AgentRunToolCall {
 
 ## Discovery scope
 
-Results are scoped to runs started by the agent you call `listSuspendedRuns()` on: snapshots persist the owning agent's id, so runs started by other agents on the same Mastra instance aren't returned. In [supervisor setups](https://mastra.ai/docs/agents/agent-approval) the supervisor sees its outer run — the one to resume — while a subagent's inner run is only visible from the subagent itself. Filter by `threadId` and `resourceId` to scope results to one conversation.
+Results are scoped to runs started by the agent you call `listSuspendedRuns()` on: snapshots persist the owning agent's id, so runs started by other agents on the same Mastra instance aren't returned. In [supervisor setups](https://mastra.ai/docs/agents/agent-approval) the supervisor sees its outer run (the one to resume), while a subagent's inner run is only visible from the subagent itself. Filter by `threadId` and `resourceId` to scope results to one conversation.
 
 Run snapshots are only persisted while a run is waiting on input and are deleted when it finishes, so suspended runs are the only runs discoverable from storage. Suspended runs only survive restarts when the Mastra instance has a persistent [storage provider](https://mastra.ai/docs/storage/overview) configured. With the default in-memory store, snapshots are lost on restart.
 

package/.docs/reference/ai-sdk/chat-route.md

@@ -32,7 +32,7 @@ export const mastra = new Mastra({
 })
 ```
 
-You can also use dynamic agent routing based on an `agentId`. The URL `/chat/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
+You can also use runtime-defined agent routing based on an `agentId`. The URL `/chat/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/ai-sdk/network-route.md

@@ -30,7 +30,7 @@ export const mastra = new Mastra({
 })
 ```
 
-You can also use dynamic agent routing based on an `agentId`. The URL `/network/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
+You can also use runtime-defined agent routing based on an `agentId`. The URL `/network/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/ai-sdk/to-ai-sdk-messages.md

@@ -2,7 +2,7 @@
 
 # toAISdkMessages()
 
-Converts messages from various input formats to AI SDK UI message format. `toAISdkMessages()` keeps the existing AI SDK v5/default behavior. If your app is typed against AI SDK v6, pass `version: 'v6'`.
+Converts messages from input formats to AI SDK UI message format. `toAISdkMessages()` keeps the existing AI SDK v5/default behavior. If your app is typed against AI SDK v6, pass `version: 'v6'`.
 
 `version: 'v6'` uses the MessageList AI SDK v6 UI output path. MessageList input detection and ingestion remain unchanged.
 

package/.docs/reference/ai-sdk/to-ai-sdk-v4-messages.md

@@ -2,7 +2,7 @@
 
 # toAISdkV4Messages()
 
-Converts messages from various input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+Converts messages from input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
 
 ## Usage example
 

package/.docs/reference/ai-sdk/to-ai-sdk-v5-messages.md

@@ -2,7 +2,7 @@
 
 # toAISdkV5Messages()
 
-Converts messages from various input formats to AI SDK V5 (and later) UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5+ `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+Converts messages from input formats to AI SDK V5 (and later) UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5+ `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
 
 ## Usage example
 

package/.docs/reference/ai-sdk/workflow-route.md

@@ -32,7 +32,7 @@ export const mastra = new Mastra({
 })
 ```
 
-You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
+You can also use runtime-defined workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/ai-sdk/workflow-snapshot-to-stream.md

@@ -36,10 +36,10 @@ export async function GET(req: Request) {
 
 ## Returns
 
-`ReadableStream` — A stream of AI SDK UIMessage data parts containing:
+`ReadableStream`: A stream of AI SDK UIMessage data parts containing:
 
 - A `start` marker
-- A `WorkflowDataPart` with the overall workflow status and all step summaries
+- A `WorkflowDataPart` with the workflow status and all step summaries
 - A `WorkflowStepDataPart` for each step with its full output
 - A `finish` marker
 

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