@mastra/mcp-docs-server 1.2.16-alpha.3 → 1.2.16-alpha.6

package/.docs/docs/agents/a2a.md

@@ -2,7 +2,7 @@
 
 # A2A (Agent-to-Agent)
 
-Mastra supports version 0.3.0 of the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
+Mastra supports version 0.3.0 of the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents or consume remote A2A agents as Mastra subagents. You can also call A2A endpoints with the JavaScript client SDK.
 
 A2A is an open protocol for delegating work to agents across network, framework, vendor, and language boundaries. A remote agent keeps its own tools, prompts, memory, workflows, and infrastructure private while exposing a protocol endpoint that other systems can discover and call.
 

package/.docs/docs/agents/guardrails.md

@@ -188,16 +188,16 @@ Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) ref
 
 ### Enforce cost limits
 
-The `CostGuardProcessor()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate, metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
+The `TokenCostControl()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate, metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
 
 ```typescript
-import { CostGuardProcessor } from '@mastra/core/processors'
+import { TokenCostControl } from '@mastra/core/processors'
 
 export const budgetedAgent = new Agent({
   id: 'budgeted-agent',
   name: 'Budgeted Agent',
   inputProcessors: [
-    new CostGuardProcessor({
+    new TokenCostControl({
       maxCost: 5.0,
       scope: 'thread',
       window: '24h',
@@ -206,7 +206,7 @@ export const budgetedAgent = new Agent({
 })
 ```
 
-Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
+Visit [`TokenCostControl()`](https://mastra.ai/reference/processors/token-cost-control) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
 
 ## Processor strategies
 
@@ -232,18 +232,19 @@ All processors support an `onViolation` callback that fires when a policy violat
 The callback receives a `ProcessorViolation` object with `processorId`, `message`, and `detail` (processor-specific metadata).
 
 ```typescript
-import { CostGuardProcessor, ModerationProcessor, PIIDetector } from '@mastra/core/processors'
+import { TokenCostControl, ModerationProcessor, PIIDetector } from '@mastra/core/processors'
 
 // Alert when cost limits are exceeded
-const costGuard = new CostGuardProcessor({
+const tokenCostControl = new TokenCostControl({
   maxCost: 10.0,
   scope: 'resource',
   window: '30d',
+  strategy: 'warn',
 })
 
-costGuard.onViolation = ({ processorId, message, detail }) => {
+tokenCostControl.onViolation = ({ processorId, message, detail }) => {
   alertSystem.notify(`[${processorId}] ${message}`)
-  // detail contains: { usage, limit, totalUsage, scope, scopeKey }
+  // detail contains: { usage, limit, totalUsage, scope, scopeKey, threshold }
 }
 
 // Log moderation violations
@@ -257,9 +258,9 @@ moderation.onViolation = ({ processorId, message, detail }) => {
 }
 ```
 
-The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `CostGuardProcessor`), the callback also fires on warnings without blocking the request.
+The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `TokenCostControl`), the callback also fires on warnings without blocking the request.
 
-Errors thrown by the callback are silently caught to prevent interfering with the processor's main logic.
+Errors thrown by runner-invoked callbacks after `abort()` are silently caught to prevent interfering with the processor's main logic. On the `TokenCostControl` warning path, callback errors are caught and logged through the Mastra logger.
 
 For more on how violation callbacks integrate with the processor pipeline, see [Violation callbacks](https://mastra.ai/docs/agents/processors) in the Processors documentation.
 

package/.docs/docs/agents/overview.md

@@ -160,6 +160,8 @@ Once registered, it can be called from workflows, tools, or other agents, and ha
 Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
 
 > **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages and inspect tool calls and responses, plus debug agent behavior.
+>
+> Use [Agent Builder](https://agent-builder.mastra.ai) to create and manage a fully stored agent through a browser instead of defining it in TypeScript.
 
 ## Use your agent
 

package/.docs/docs/agents/processors.md

@@ -494,7 +494,7 @@ These fields are overridable per call:
 
 ### Tenant scoping
 
-By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Users never see each other's cached responses.
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. An agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Users never see each other's cached responses.
 
 Override explicitly when you need a different scope:
 
@@ -538,7 +538,7 @@ For a custom backend, extend `MastraServerCache` and implement its abstract meth
 
 `ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
 
-This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model. The key is created _after_ memory has loaded and earlier input processors have run, and each step in an agentic tool loop is independently cached.
+The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model. The key is created _after_ memory has loaded and earlier input processors have run, and each step in an agentic tool loop is independently cached.
 
 ### What's in the cache key
 
@@ -785,7 +785,7 @@ For streaming, access metadata from the `finish` chunk payload or the `stream.re
 
 ### Use workflows as processors
 
-You can use Mastra workflows as processors to create complex processing pipelines with parallel execution, conditional branching, and error handling:
+You can use Mastra workflows as processors to create complex processing pipelines with parallel execution and conditional branching, plus error handling:
 
 ```typescript
 import { createWorkflow, createStep } from '@mastra/core/workflows'
@@ -842,7 +842,7 @@ When an agent is registered with Mastra, processor workflows are automatically r
 
 ### Retry mechanism
 
-Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks, output validation, or iterative refinement:
+Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks or output validation, including iterative refinement:
 
 ```typescript
 import type { Processor } from '@mastra/core/processors'
@@ -892,7 +892,7 @@ For `StreamErrorRetryProcessor`, also set its `maxRetries` to the same value. It
 All processors expose an `onViolation` property that fires whenever a policy violation is detected, both when `abort()` is called (block strategy) and when a processor issues a warning (warn strategy). Use it for alerting, logging, or side effects without affecting the processor's main logic:
 
 ```typescript
-import { ModerationProcessor, CostGuardProcessor } from '@mastra/core/processors'
+import { ModerationProcessor, TokenCostControl } from '@mastra/core/processors'
 
 const moderation = new ModerationProcessor({
   model: 'openai/gpt-5-nano',
@@ -904,13 +904,13 @@ moderation.onViolation = ({ processorId, message, detail }) => {
   monitor.track('processor_violation', { processorId, message, detail })
 }
 
-const costGuard = new CostGuardProcessor({
+const tokenCostControl = new TokenCostControl({
   maxCost: 10.0,
   scope: 'resource',
   window: '30d',
 })
 
-costGuard.onViolation = ({ processorId, message, detail }) => {
+tokenCostControl.onViolation = ({ processorId, message, detail }) => {
   alertSystem.notify(`[${processorId}] ${message}`)
 }
 ```
@@ -921,7 +921,7 @@ The callback receives a `ProcessorViolation` object with:
 - `message`: A human-readable description of what was violated
 - `detail`: Processor-specific metadata (e.g. cost usage, detected PII types, moderation categories)
 
-`onViolation` is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any custom processor can use it too. The runner automatically invokes it when any processor calls `abort()`. Errors thrown inside the callback are silently caught to prevent interfering with the processor pipeline.
+`onViolation` is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any custom processor can use it too. The runner automatically invokes it when any processor calls `abort()`. Errors thrown inside the callback are caught to prevent interfering with the processor pipeline.
 
 ### Abort and tripwire chunks
 

package/.docs/docs/agents/structured-output.md

@@ -6,7 +6,7 @@ Structured output lets an agent return an object that matches the shape defined
 
 ## When to use structured output
 
-Use structured output when you need an agent to return a data object rather than text. Having well defined fields can make it simpler to pull out the values you need for API calls, UI rendering, or application logic.
+Use structured output when you need an agent to return a data object rather than text. Having well defined fields can make it simpler to pull out the values you need for API calls and UI rendering, as well as application logic.
 
 ## Define schemas
 

package/.docs/docs/agents/using-tools.md

@@ -2,7 +2,7 @@
 
 # Tools
 
-Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
+Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
 
 **For AI agents:** Run `npx mastra api tool execute weather-tool '{"location":"San Francisco"}'` to test this tool directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api tool execute --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
 
@@ -287,7 +287,42 @@ Use `transform` when a tool returns raw data your application needs, but browser
 
 If a transform is configured and it fails, Mastra doesn't fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
 
-See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for a `transform` example. For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
+The following example redacts a secret from both targets:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const customerTool = createTool({
+  id: 'lookup-customer',
+  description: 'Looks up a customer by id',
+  inputSchema: z.object({
+    customerId: z.string(),
+  }),
+  outputSchema: z.object({
+    ssn: z.string(),
+  }),
+  execute: async ({ customerId }) => {
+    // const response = await fetch(`https://your-crm.example.com/customers/${customerId}`)
+    // const { ssn } = await response.json()
+    return {
+      ssn: '123-45-6789',
+    }
+  },
+  transform: {
+    display: {
+      output: () => ({ ssn: '***-**-****' }),
+    },
+    transcript: {
+      output: () => ({ ssn: '***-**-****' }),
+    },
+  },
+})
+```
+
+Your application code still receives the raw `ssn` from the tool. Browser-facing streams get the `display` output, and user-visible transcript messages get the `transcript` output.
+
+For more phases, including `input`, `inputDelta`, `error`, `approval`, `suspend`, and `resume`, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool). For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
 
 ## Run logic around tool calls
 
@@ -469,16 +504,18 @@ Note that for subagents, you'll see two different identifiers in stream response
 
 Mastra includes agent-agnostic built-in tools in `@mastra/core/tools` that add interactive and organizational capabilities to any agent.
 
-| Tool            | Purpose                                              |
-| --------------- | ---------------------------------------------------- |
-| `ask_user`      | Ask the user a question and wait for their answer    |
-| `submit_plan`   | Submit a plan file for user approval                 |
-| `task_write`    | Create or replace a structured task list             |
-| `task_update`   | Update one tracked task by ID                        |
-| `task_complete` | Mark one tracked task completed                      |
-| `task_check`    | Check task list completion status                    |
-| `webSearchTool` | Run provider-native web search with the active model |
-| `webFetchTool`  | Fetch a web page by URL and return its text content  |
+Each tool has two names: the export you import, and the tool ID the model sees in tool calls, traces, and `toolName` fields.
+
+| Export             | Tool ID              | Purpose                                             |
+| ------------------ | -------------------- | --------------------------------------------------- |
+| `askUserTool`      | `ask_user`           | Ask the user a question and wait for their answer   |
+| `submitPlanTool`   | `submit_plan`        | Submit a plan file for user approval                |
+| `taskWriteTool`    | `task_write`         | Create or replace a structured task list            |
+| `taskUpdateTool`   | `task_update`        | Update one tracked task by ID                       |
+| `taskCompleteTool` | `task_complete`      | Mark one tracked task completed                     |
+| `taskCheckTool`    | `task_check`         | Check task list completion status                   |
+| `webSearchTool`    | `<provider.defined>` | Run the active provider's native web search         |
+| `webFetchTool`     | `web_fetch`          | Fetch a web page by URL and return its text content |
 
 ### Use provider web search
 
@@ -501,6 +538,8 @@ export const researchAgent = new Agent({
 
 `webSearchTool` supports OpenAI, Anthropic, Google Gemini, and xAI models. If Mastra can't infer one of those providers from the active model, the agent run fails with a `MastraError`.
 
+The resolved tool ID comes from the provider: `openai.web_search`, `anthropic.web_search_20250305`, `google.google_search`, or `xai.web_search`.
+
 The `search` key is only the agent-local tool name. Use any key. The `webSearchTool` value tells Mastra to use provider web search.
 
 ### Fetch a web page

package/.docs/docs/browser/overview.md

@@ -10,7 +10,6 @@ Mastra supports three SDK providers and one CLI provider:
 - [**Stagehand**](https://mastra.ai/integrations/browsers/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
 - [**FirecrawlBrowser**](https://mastra.ai/integrations/browsers/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
 - [**BrowserViewer**](https://mastra.ai/integrations/browsers/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
-- [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
 ## When to use browser
 
@@ -24,7 +23,7 @@ Use browser when your agent needs to:
 
 ## How it works
 
-When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser: navigating to URLs, selecting elements, typing text, and reading page content.
+When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser. It can open URLs and select elements. It can also type text and read page content.
 
 Each provider offers a different set of tools optimized for its approach.
 
@@ -176,12 +175,32 @@ const browser = new AgentBrowser({
 })
 ```
 
+## Record browser sessions
+
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
+AgentBrowser and StagehandBrowser can opt into recording for reviewing, sharing, or debugging browser runs. Configure `outputDir` to add the recording tools:
+
+```typescript
+import { join } from 'node:path'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+export const browser = new AgentBrowser({
+  recording: {
+    outputDir: join(process.cwd(), 'browser-recordings'),
+  },
+})
+```
+
+StagehandBrowser accepts the same `recording` option. The agent uses `browser_record` to start, check, and stop a recording, and `browser_record_caption` to label major actions. Stopping saves the video and lets the agent return its path. A custom `outputPath` must be absolute and stay inside `recording.outputDir`.
+
+Recordings use Motion-JPEG AVI and don't require `ffmpeg`. The default maximum duration is 30 seconds, with a 120-second hard cap. The default maximum frame size is 1024 × 720, captions are limited to 80 characters, and only one recording can be active per process.
+
 ## Next steps
 
 - [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
 - [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
 - [Firecrawl](https://mastra.ai/integrations/browsers/firecrawl)
-- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [BrowserViewer](https://mastra.ai/integrations/browsers/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)
 - 📹 [Mastra browser capabilities workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)

package/.docs/docs/capabilities/subagents.md

@@ -136,7 +136,7 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
 - Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
 
-Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text. The parent model reads this as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -237,7 +237,7 @@ const stream = await parentAgent.stream('Research AI trends', {
 })
 ```
 
-Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn to produce a text response incorporating the feedback, but only if the current iteration is still active (e.g., after tool calls), otherwise no extra turn is granted.
+Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn for a text response that incorporates the feedback. The extra turn is granted only while the current iteration is active (e.g., after tool calls).
 
 ## Memory isolation
 

package/.docs/docs/datasets/running-experiments.md

@@ -69,7 +69,7 @@ Because the threads belong to the caller's resource, resource-scoped memory feat
 - Resource-scoped working memory updates persist to the resource, and later items in the run see updates made by earlier items.
 - Resource-scoped semantic recall can surface the resource's prior conversations to the experiment, and experiment transcripts become recallable in that resource's later conversations.
 
-This is useful when you want to evaluate an agent against a real user's accumulated context. If you don't want experiment runs touching real user state, run the experiment with a dedicated evaluation resource id instead.
+Use this approach to evaluate an agent against a real user's accumulated context. To keep experiment runs from touching real user state, use a dedicated evaluation resource id instead.
 
 Thread injection is skipped in the following cases:
 
@@ -353,7 +353,7 @@ In [Studio](https://mastra.ai/docs/studio/overview), edit a dataset item to auth
 ### Limitations
 
 - **No tool span for mocked calls.** A mocked call returns its output before the tool executes, so it doesn't create a tool span. Trajectory scorers backed by stored traces may therefore not see mocked tool calls. Trajectory extraction that falls back to the agent's message output still sees them, so trajectory scoring can differ depending on your observability configuration.
-- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter doesn't support them and rejects writes that carry tool mocks or a tool mock report. All dataset storage adapters persist `unmockedToolPolicy`.
+- **Storage support.** The LibSQL, PostgreSQL, MongoDB, and Spanner adapters persist tool mocks and tool mock reports, while the MySQL adapter rejects writes that carry either one. All dataset storage adapters persist `unmockedToolPolicy`.
 
 ## Async experiments
 

package/.docs/docs/deployment/overview.md

@@ -2,7 +2,7 @@
 
 # Deploy
 
-Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server, integrate with an existing web framework, deploy to cloud providers, or use [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) for observability, Studio, and server deployment.
+Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server or integrate with an existing web framework. Other options include cloud providers and [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) for observability, Studio, and server deployment.
 
 ## Runtime support
 
@@ -73,10 +73,10 @@ Use these guides when adding Mastra to an existing Next.js or Astro application.
 
 ## Workflow runners
 
-Mastra workflows run using the built-in execution engine by default. For production workloads requiring managed infrastructure, workflows can also be deployed to specialized platforms like [Inngest](https://www.inngest.com) that provide step memoization, automatic retries, and real-time monitoring.
+Mastra workflows run using the built-in execution engine by default. For production workloads requiring managed infrastructure, workflows can also be deployed to specialized platforms like [Inngest](https://www.inngest.com) that provide step memoization and automatic retries, with real-time monitoring.
 
 Visit the [Workflow Runners guide](https://mastra.ai/docs/deployment/workflow-runners) for execution options and the [Inngest deployment guide](https://mastra.ai/integrations/deploy/inngest) for setup instructions.
 
 ## Workers
 
-For production deployments, Mastra can run workflow orchestration, cron scheduling, and background tool execution in dedicated worker processes separate from the API server. This lets you scale each concern independently and isolate failures. See [Workers](https://mastra.ai/docs/deployment/workers) for details.
+For production deployments, Mastra can run workflow orchestration and cron scheduling, along with background tool execution in dedicated worker processes separate from the API server. This lets you scale each concern independently and isolate failures. See [Workers](https://mastra.ai/docs/deployment/workers) for details.

package/.docs/docs/deployment/sandbox.md

@@ -69,7 +69,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Two Vercel-specific requirements:
+Vercel has two additional requirements:
 
 - `timeout` can't exceed the maximum sandbox lifetime of your plan, 45 minutes on Pro. A higher value fails the deploy with a 400 from the Vercel API.
 - Declare the server port in `ports`. Vercel exposes only ports declared at creation, unlike E2B and Daytona.

package/.docs/docs/deployment/workers.md

@@ -126,15 +126,15 @@ mastra worker start orchestration
 
 ## Network architecture
 
-Workers are internal infrastructure. They're not exposed to end users and don't need their own subdomain, public URL, or inbound HTTP route.
+Workers are internal infrastructure. They're not exposed to end users and don't need their own subdomain or public URL, including an inbound HTTP route.
 
 In a split deployment:
 
-- **The API server is the only public-facing process**: It serves all client HTTP requests, including REST endpoints, agent interactions, workflow triggers, and any custom routes.
+- **The API server is the only public-facing process**: It serves all client HTTP requests. These requests include REST endpoints and agent interactions, plus workflow triggers and custom routes.
 - **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
 - **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
-All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. If a worker-related feature needs an HTTP route (for example, token minting for a voice integration), that route runs on the API server, not on the worker process.
+All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. HTTP routes for worker-related features run on the API server rather than the worker process. One example is token minting for a voice integration.
 
 ## Deploy split workers
 
@@ -337,7 +337,7 @@ In a fully split deployment, the orchestration worker delegates workflow step ex
 MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 ```
 
-Without this variable, the orchestration worker attempts to execute steps in its own process. That process doesn't have access to the full Mastra runtime in a split deployment.
+Without this variable, the orchestration worker attempts to execute steps in its own process, which doesn't have access to the full Mastra runtime in a split deployment.
 
 The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/server/auth/workers) for server configuration and other credential formats.
 
@@ -361,7 +361,7 @@ Run exactly one scheduler worker. Multiple schedulers polling the same storage c
 
 ### Crash recovery
 
-A distributed PubSub backend persists unacknowledged events so orchestration and background task workers can resume processing after a restart. If the API is unavailable when the orchestration worker requests step execution, the request fails and the event is delivered again. An event can be processed more than once, so handlers should be idempotent when possible.
+A distributed PubSub backend persists unacknowledged events, which lets orchestration and background task workers resume after a restart. When the API is unavailable, a failed step-execution request causes the event to be delivered again. Because an event can be processed more than once, handlers should be idempotent when possible.
 
 The scheduler calculates the next fire time from the current time after it restarts. It doesn't replay schedules that elapsed while it was unavailable.
 

package/.docs/docs/deployment/workflow-runners.md

@@ -6,7 +6,7 @@ Mastra [workflows](https://mastra.ai/docs/workflows/overview) can be executed us
 
 ## Inngest
 
-Inngest is a developer platform for running background workflows without managing infrastructure. Mastra workflows can be deployed to Inngest, which provides step memoization, automatic retries, real-time monitoring, and suspend/resume capabilities.
+Inngest is a developer platform for running background workflows without managing infrastructure. Mastra workflows can be deployed to Inngest for step memoization and automatic retries. Inngest also provides real-time monitoring and suspend/resume capabilities.
 
 Visit the [Inngest deployment guide](https://mastra.ai/integrations/deploy/inngest) for setup instructions and the [Inngest workflow example](https://github.com/mastra-ai/mastra/tree/main/examples/inngest) for a complete implementation.
 

package/.docs/docs/editor/overview.md

@@ -14,6 +14,8 @@ A [deployed Studio](https://mastra.ai/docs/studio/deployment) makes Editor avail
 
 Use Editor when an agent is defined in code but the people responsible for its behavior shouldn't edit the codebase. It works well when instructions or tools change often and need testing before they reach users. If developers own every change and release agent configuration with the application, keep the [agent configuration in code](https://mastra.ai/docs/agents/overview) instead.
 
+Use [Agent Builder](https://agent-builder.mastra.ai) instead when collaborators need to create and manage fully stored agents in a browser rather than start from agents defined in code.
+
 ## Quickstart
 
 Install `@mastra/editor`. This quickstart uses LibSQL to store Editor changes:
@@ -304,7 +306,7 @@ Version selection supports:
 - Compare two versions in an A/B test.
 - Give a draft to a small group before publishing it for everyone.
 - Keep production on the published version while staging uses the latest draft.
-- Pin a customer to a particular version.
+- Pin a customer to a specific version.
 
 The same version controls work when a supervisor calls sub-agents. Developers can test a draft sub-agent without changing the rest of the system.
 

package/.docs/docs/evals/custom-scorers.md

@@ -104,7 +104,7 @@ console.log(result.analyzeStepResult) // { hasSources: true, sources: ["Wikipedi
 
 ### Agent Type for Agent Evaluation
 
-For type safety and compatibility with both live agent scoring and trace scoring, use `type: 'agent'` when creating scorers for agent evaluation. This allows you to use the same scorer for an agent and also use it to score traces:
+For type safety and compatibility with both live agent scoring and trace scoring, use `type: 'agent'` when creating scorers for agent evaluation. The same scorer can evaluate an agent and score traces:
 
 ```typescript
 const myScorer = createScorer({

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

@@ -113,7 +113,7 @@ Semantics:
 - `result.turnResults[i]` reports each turn's `gateResults`, `thresholdResults`, and `scores`, so a failure points at the exact turn. Across multiple conversations, turn results are averaged by turn index.
 - A turn with no `gates` or `scorers` advances the conversation.
 - Top-level `scorers`/`gates` still run as a whole over the accumulated output, so you can combine "this turn must call the tool" with "the answer mentions Brooklyn."
-- When the agent has storage configured, each per-turn scorer/gate result is persisted like top-level scores, so per-turn outcomes appear in your scores store. Each stored per-turn score is labeled with its turn index (`metadata.turnIndex`), shares the conversation's `threadId`, and links to that turn's own trace span.
+- When the agent has storage configured, each per-turn scorer/gate result is persisted like top-level scores, so per-turn outcomes appear in your scores store. Each stored per-turn score uses its turn index as a label (`metadata.turnIndex`) and shares the conversation's `threadId`. It also includes a link to that turn's trace span.
 
 Use `inputs` when a single whole-conversation score over the whole conversation is enough. Use `turns` when correctness depends on individual turns. `turns` can't be combined with `input` or `inputs` in the same data item.
 

package/.docs/docs/evals/overview.md

@@ -4,9 +4,9 @@
 
 While traditional software tests have clear pass/fail conditions, AI outputs are non-deterministic, they can vary with the same input. **Scorers** help bridge this gap by providing quantifiable metrics for measuring agent quality.
 
-Scorers are automated tests that evaluate Agents outputs using model-graded, rule-based, and statistical methods. Scorers return **scores**: numerical values (typically between 0 and 1) that quantify how well an output meets your evaluation criteria. These scores enable you to objectively track performance, compare different approaches, and identify areas for improvement in your AI systems. Scorers can be customized with your own prompts and scoring functions.
+Scorers are automated tests that evaluate Agents outputs using model-graded, rule-based, and statistical methods. Scorers return **scores**: numerical values (typically between 0 and 1) that quantify how well an output meets your evaluation criteria. These scores enable you to objectively track performance and compare different approaches while identifying areas for improvement in your AI systems. Scorers can be customized with your own prompts and scoring functions.
 
-Scorers can be run in the cloud, capturing real-time results. But scorers can also be part of your CI/CD pipeline, allowing you to test and monitor your agents over time.
+Scorers can run in the cloud to capture real-time results. Scorers can also be part of your CI/CD pipeline for testing and monitoring agents over time.
 
 > **📹 Watch:** Watch [Mastra evals overview](https://www.youtube.com/watch?v=12WN6u2DrBk) for an introduction to evals and how to reason about agent quality.
 
@@ -113,7 +113,7 @@ For the step-level `scorers` API, see the [Step class reference](https://mastra.
 
 ### How live evaluations work
 
-**Asynchronous execution**: Live evaluations run in the background without blocking your agent responses or workflow execution. This ensures your AI systems maintain their performance while still being monitored.
+**Asynchronous execution**: Live evaluations run in the background without blocking your agent responses or workflow execution. Your AI systems remain responsive while live evaluations monitor them.
 
 **Sampling control**: The `sampling.rate` parameter (0-1) controls what percentage of outputs get scored:
 

package/.docs/docs/getting-started/develop.md

@@ -44,7 +44,7 @@ Mastra provides a skill and a CLI to help your coding agent write high-quality M
 
 ### Mastra skill
 
-AI models may not have up-to-date knowledge of Mastra's APIs. Use the [Mastra skill](https://github.com/mastra-ai/skills) to give your coding agent implementation guidance, best practices, and instructions for fetching the latest Mastra documentation.
+AI models may not have up-to-date knowledge of Mastra's APIs. Use the [Mastra skill](https://github.com/mastra-ai/skills) to give your coding agent implementation guidance and best practices, including instructions for fetching the latest Mastra documentation.
 
 Install the skill manually with:
 

package/.docs/docs/harness/agent-controller.md

@@ -6,7 +6,7 @@
 
 `AgentController` is a shared runtime host for interactive agent applications. It coordinates modes, models, storage, workspaces, tool approvals, subagents, and channels. Each user or active task works through an isolated [`Session`](https://mastra.ai/reference/agent-controller/session).
 
-[Mastra Code](https://code.mastra.ai) is the flagship AgentController implementation. It's a terminal-based coding agent with multi-model support, persistent conversations, and plan-then-execute workflows. Read [Building a coding agent](https://mastra.ai/blog/building-a-coding-agent) for a step-by-step guide.
+[Mastra Code](https://code.mastra.ai) and [Mastra Factory](https://factory.mastra.ai) are the flagship AgentController implementations. They're coding agents with multi-model support, persistent conversations, and plan-then-execute workflows. Read [Building a coding agent](https://mastra.ai/blog/building-a-coding-agent) for a step-by-step TUI guide.
 
 ## When to use the Agent Controller
 
@@ -341,7 +341,7 @@ Point each platform webhook at the controller-specific route:
 /api/agent-controllers/<CONTROLLER_ID>/channels/<PLATFORM>/webhook
 ```
 
-Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads; an existing thread keeps its stored resource ID.
+Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads. An existing thread keeps its stored resource ID.
 
 Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. A channel session starts with controller defaults, so this is where you set its model and memory settings. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
 

package/.docs/docs/harness/overview.md

@@ -4,7 +4,7 @@
 
 A harness lets an agent pursue long-running, complex goals while keeping its work durable, visible, and steerable. It preserves progress across retries and interruptions, while giving people and other systems a way to inspect progress, add context, approve actions, redirect the agent, or stop it.
 
-Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
+Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories (like [Mastra Factory](https://factory.mastra.ai)) that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
 
 In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
 

package/.docs/docs/long-running-agents/background-tasks.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.29.0`
 
-Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement while the LLM continues responding. The task then runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
 
 ## When to use background tasks
 
@@ -273,7 +273,7 @@ await mastra.backgroundTaskManager?.resume(taskId, {
 
 ### What happens to the agent loop
 
-When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion, its result is added to the message list, and the agent runs a follow-up turn, all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
+When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion and adds its result to the message list. The agent then runs a follow-up turn, all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
 
 ### Re-registering the executor on resume
 

package/.docs/docs/long-running-agents/goals.md

@@ -114,5 +114,6 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 ## Related
 
 - [Supervisor agents](https://mastra.ai/docs/capabilities/subagents): `isTaskComplete` and the rubric scorer
-- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers): how the objective is projected into context
-- [Memory storage](https://mastra.ai/docs/storage/overview): the storage backend goals require
+- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers): How the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/storage/overview): The storage backend goals require
+- [Mastra Factory](https://factory.mastra.ai) and [Mastra Code](https://code.mastra.ai): Examples of goal-driven coding agents

package/.docs/docs/long-running-agents/signals.md

@@ -151,7 +151,7 @@ Notification inbox storage is available in the storage adapters that support ric
 
 ### Send processor context
 
-Processors can send reactive signals during a run. A processor should inspect the chat history, react to a specific trigger, and avoid sending the same context more than once.
+Processors can send reactive signals during a run. A processor should inspect the chat history and react to a specific trigger without sending the same context more than once.
 
 The following example demonstrates a processor that injects `AGENTS.md` instructions after a tool call reads an `AGENTS.md` file.
 
@@ -350,7 +350,7 @@ Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `
 - `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
 - `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
 
-Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server. Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
+Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them. React's thread signal path falls back to the legacy `/signals` route when it detects an older server. Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
 ### Approve tool calls
 

package/.docs/docs/mastra-platform/deploy.md

@@ -93,7 +93,7 @@ The region is fixed when the environment is created. Databases attached to an en
 
 Preflight validates the built output before anything includes, and only flags issues in your own code:
 
-- **Local storage paths**: A hard block. File-backed storage (for example `file:./mastra.db`) is lost on every deploy. Preflight passes when the path is guarded by an environment variable that's set locally, stored on the platform, or provided by a managed database:
+- **Local storage paths**: A hard block. File-backed storage (for example `file:./mastra.db`) is lost on every deploy. Preflight passes when the path is guarded by an environment variable that's set locally or stored on the platform, including values provided by a managed database:
 
   ```ts
   import { LibSQLStore } from '@mastra/libsql'