@mastra/mcp-docs-server 1.2.23-alpha.1 → 1.2.23-alpha.11

package/.docs/docs/guides/streaming.md

@@ -8,14 +8,11 @@ Mastra supports real-time, incremental responses from agents and workflows, allo
 
 ## Getting started
 
-Mastra's streaming API adapts based on your model version:
-
-- **`.stream()`**: For V2 models, supports **AI SDK v5** and later (`LanguageModelV2`).
-- **`.streamLegacy()`**: For V1 models, supports **AI SDK v4** (`LanguageModelV1`).
+[`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) is the standard streaming API for agents. It returns a `MastraModelOutput` that exposes `textStream` for progressive text and promises such as `text`, `steps`, and `usage` that resolve when the stream finishes.
 
 ## Streaming with agents
 
-You can pass a single string for basic prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
+Pass a single string for a basic prompt. When providing multiple pieces of context, use an array of strings. An array of message objects with `role` and `content` gives you precise control over roles and conversational flow.
 
 ### Using `Agent.stream()`
 
@@ -33,7 +30,7 @@ for await (const chunk of stream.textStream) {
 
 Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
-> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/harness/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
+> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/harness/background-tasks), use `stream()` with the [`untilIdle` option](https://mastra.ai/reference/streaming/agents/stream), such as `untilIdle: true`, to keep the stream open until those tasks complete and the agent has had a chance to respond to their results. This option requires agent memory.
 
 ### Output from `Agent.stream()`
 
@@ -51,54 +48,58 @@ Here are some questions to consider:
 An agent stream provides access to these response properties:
 
 - **`stream.textStream`**: A readable stream that emits text chunks.
-- **`stream.text`**: Promise that resolves to the full text response.
-- **`stream.finishReason`**: The reason the agent stopped streaming.
-- **`stream.usage`**: Token usage information.
+- **`stream.text`**: A promise that resolves to the full text response.
+- **`stream.steps`**: A promise that resolves to the completed model steps.
+- **`stream.finishReason`**: A promise that resolves to the reason the agent stopped streaming.
+- **`stream.usage`**: A promise that resolves to token usage information.
+- **`stream.objectStream`** and **`stream.object`**: Partial and final structured output when `structuredOutput` is passed.
 
-### AI SDK v5+ Compatibility
+See the [`MastraModelOutput` reference](https://mastra.ai/reference/streaming/agents/MastraModelOutput) for the complete set of properties.
 
-AI SDK v5 (and later) uses `LanguageModelV2` for the model providers. If you are getting an error that you are using an AI SDK v4 model you will need to upgrade your model package to the next major version.
+### AI SDK integration
 
-For integration with AI SDK v5+, use the `toAISdkV5Stream()` utility from `@mastra/ai-sdk` to convert Mastra streams to AI SDK-compatible format:
+Use `toAISdkStream()` and `toAISdkMessages()` to convert Mastra streams and stored messages to AI SDK-compatible formats. The converters default to AI SDK v5 for backward compatibility. Pass the version that matches your installed AI SDK, such as `version: 'v7'` for AI SDK v7.
 
 ```typescript
-import { toAISdkV5Stream } from '@mastra/ai-sdk'
+import { toAISdkStream } from '@mastra/ai-sdk'
 
 const testAgent = mastra.getAgent('testAgent')
-
 const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
 
-// Convert to AI SDK v5+ compatible stream
-const aiSDKStream = toAISdkV5Stream(stream, { from: 'agent' })
+const aiSDKStream = toAISdkStream(stream, {
+  from: 'agent',
+  version: 'v7',
+})
 ```
 
-For converting messages to AI SDK v5+ format, use the `toAISdkV5Messages()` utility from `@mastra/ai-sdk/ui`:
+Convert stored messages for `useChat()`'s `initialMessages` with `toAISdkMessages()`:
 
 ```typescript
-import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+import { toAISdkMessages } from '@mastra/ai-sdk/ui'
 
-const messages = [{ role: 'user', content: 'Hello' }]
-const aiSDKMessages = toAISdkV5Messages(messages)
+const initialMessages = toAISdkMessages([{ role: 'user', content: 'Hello' }], { version: 'v7' })
 ```
 
+For route handlers, see [AI SDK UI](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui), which covers `handleChatStream()`, `handleWorkflowStream()`, and `handleNetworkStream()`. Pass the version that matches your installed AI SDK to these handlers too. See the [`toAISdkStream()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-stream) and [`toAISdkMessages()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-messages) references for all options.
+
 ## Streaming with workflows
 
 Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRun()`.
 
 ### Using `Run.stream()`
 
-The `stream()` method returns a `ReadableStream` of events directly.
+The `stream()` method returns a `WorkflowRunOutput`. Its `fullStream` property is a `ReadableStream` of workflow events.
 
 ```typescript
 const run = await testWorkflow.createRun()
 
-const stream = await run.stream({
+const stream = run.stream({
   inputData: {
     value: 'initial data',
   },
 })
 
-for await (const chunk of stream) {
+for await (const chunk of stream.fullStream) {
   console.log(chunk)
 }
 ```
@@ -115,11 +116,7 @@ The event structure includes `runId` and `from` at the top level, making it easi
   runId: '1eeaf01a-d2bf-4e3f-8d1b-027795ccd3df',
   from: 'WORKFLOW',
   payload: {
-    stepName: 'step-1',
-    args: { value: 'initial data' },
-    stepCallId: '8e15e618-be0e-4215-a5d6-08e58c152068',
-    startedAt: 1755121710066,
-    status: 'running'
+    workflowId: 'testWorkflow'
   }
 }
 ```
@@ -138,26 +135,45 @@ Events emitted from agents or workflows represent different stages of generation
 
 ## Event types
 
-Below is a complete list of events emitted from `.stream()`. Depending on whether you’re streaming from an **agent** or a **workflow**, only a subset of these events will occur:
+Agent and workflow streams emit different event types during execution.
+
+### Agent events
+
+Common agent events include:
+
+- **`start`**: The agent run begins.
+- **`text-start`**, **`text-delta`**, and **`text-end`**: The start and end events mark text generation boundaries. Delta events carry incremental text.
+- **`reasoning-start`**, **`reasoning-delta`**, and **`reasoning-end`**: The start and end events mark reasoning generation boundaries. Delta events carry incremental reasoning.
+- **`tool-call`** and **`tool-result`**: A tool is called and returns a result.
+- **`step-start`** and **`step-finish`**: A model step begins and ends.
+- **`finish`**: The agent run completes.
+
+This list isn't exhaustive. See the [`ChunkType` reference](https://mastra.ai/reference/streaming/ChunkType) for all agent chunk types and payloads.
+
+### Workflow events
+
+Workflow events include:
 
-- **start**: Marks the beginning of an agent or workflow run.
-- **step-start**: Indicates a workflow step has begun execution.
-- **text-delta**: Incremental text chunks as they're generated by the LLM.
-- **tool-call**: When the agent decides to use a tool, including the tool name and arguments.
-- **tool-result**: The result returned from tool execution.
-- **step-finish**: Confirms that a specific step has fully finalized, and may include metadata like the finish reason for that step.
-- **finish**: When the agent or workflow completes, including usage statistics.
+- **`workflow-start`**: The workflow run begins.
+- **`workflow-step-start`**: A workflow step begins.
+- **`workflow-step-output`**: A step emits custom output.
+- **`workflow-step-progress`**: A step reports progress.
+- **`workflow-step-result`**: A step completes with a result.
+- **`workflow-finish`**: The workflow run completes.
+- **`workflow-paused`**, **`workflow-step-suspended`**, and **`workflow-canceled`**: The workflow run is interrupted.
+
+See the [`Run.stream()` reference](https://mastra.ai/reference/streaming/workflows/stream) for workflow event details.
 
 ## Inspecting agent streams
 
-Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
+Iterate over `stream.fullStream` with a `for await` loop to inspect all emitted event chunks.
 
 ```typescript
 const testAgent = mastra.getAgent('testAgent')
 
 const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
 
-for await (const chunk of stream) {
+for await (const chunk of stream.fullStream) {
   console.log(chunk)
 }
 ```
@@ -295,27 +311,31 @@ The `writer` argument is passed to a workflow step's `execute` function and can
 > **Warning:** You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
 
 ```typescript
-import { createStep } from "@mastra/core/workflows";
+import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
 
 export const testStep = createStep({
+  id: 'test-step',
+  inputSchema: z.object({ url: z.url() }),
+  outputSchema: z.object({ status: z.number() }),
   execute: async ({ inputData, writer }) => {
-    const { value } = inputData;
+    const { url } = inputData
 
-    await writer?.write({
-      type: "custom-event",
-      status: "pending"
-    });
+    await writer.write({
+      type: 'custom-event',
+      status: 'pending',
+    })
 
-    const response = await fetch(...);
+    const response = await fetch(url)
 
-    await writer?.write({
-      type: "custom-event",
-      status: "success"
-    });
+    await writer.write({
+      type: 'custom-event',
+      status: 'success',
+    })
 
     return {
-      value: ""
-    };
+      status: response.status,
+    }
   },
-});
+})
 ```

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

@@ -369,7 +369,7 @@ channels: {
 }
 ```
 
-Create the session under `thread.resourceId`. A session can only bind threads it owns, so use `resolveResourceId` if you want a different owner for the mapped thread. Sessions are get-or-create per `resourceId` and `scope`, so pass `scope` when one thread needs separate sessions per install or principal.
+Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
 
 Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
 
@@ -396,6 +396,10 @@ See [Channels](https://mastra.ai/docs/channels) for adapter setup and platform-s
 
 ## Connect a UI
 
+How you connect depends on where the UI runs. A terminal UI or a server that owns the controller holds the `Session` object and subscribes to it directly. A browser UI runs in a different process, so it reaches the same session over the controller's HTTP routes with [`@mastra/client-js`](https://mastra.ai/reference/client-js/mastra-client).
+
+### Server-side sessions
+
 Subscribe to Session events for incremental updates. Read the reduced display state with [`session.displayState.get()`](https://mastra.ai/reference/agent-controller/session) when the UI needs a complete render snapshot:
 
 ```typescript
@@ -413,6 +417,50 @@ unsubscribe()
 
 Subscriptions are isolated by Session. Events from another Session on the same controller aren't delivered to this listener. Read the [Building a coding agent](https://mastra.ai/blog/building-a-coding-agent) guide for a complete TUI example.
 
+### Client-side sessions
+
+`client.getAgentController(id).session(resourceId, scope?)` returns a session client bound to one resource. Sessions are get-or-create on the server, so `create()` resumes an existing conversation instead of forking it. Pass `scope` when one resource needs independent sessions, such as one per git worktree:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({ baseUrl: 'http://localhost:4111' })
+const session = client.getAgentController('coding-controller').session('user-123')
+
+await session.create()
+
+const subscription = await session.subscribe({
+  onEvent: event => handleEvent(event),
+  onError: error => showDisconnected(error),
+  onReconnect: async () => resync(await session.state()),
+  reconnect: true,
+})
+
+// Call when the UI disconnects.
+subscription.unsubscribe()
+```
+
+`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect, so a rejected call leaves nothing running in the background. `reconnect: true` re-establishes a stream that drops after it was established, with exponential backoff.
+
+The server doesn't replay events missed while the stream was down, so read `session.state()` from `onReconnect` for the current mode, model, and thread. The client surface has no `session.displayState.get()`.
+
+Send work with `session.sendMessage(content)`, or `session.sendMessage({ content, files })` to attach base64-encoded files. The reply arrives as `message_*` events on the subscription, not as the return value of the call. Answer a `tool_approval_required` event with `session.approveTool(toolCallId, approved)`, and a `tool_suspended` event with `session.respondToToolSuspension(toolCallId, resumeData)`.
+
+`onEvent` receives every event the session emits, discriminated by `event.type`:
+
+| Group        | Events                                                                                                                                                                                                                                                                                  |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Run          | `agent_start`, `agent_end`, `usage_update`, `goal_evaluation`, `follow_up_queued`                                                                                                                                                                                                       |
+| Messages     | `message_start`, `message_update`, `message_end`                                                                                                                                                                                                                                        |
+| Tools        | `tool_input_start`, `tool_input_delta`, `tool_input_end`, `tool_start`, `tool_update`, `tool_end`, `shell_output`, `command_exit`, `tool_approval_required`, `tool_suspended`, `tool_suspension_cancelled`, `task_updated`                                                              |
+| Session      | `state_changed`, `display_state_changed`, `mode_changed`, `model_changed`, `thread_changed`, `thread_created`, `thread_deleted`, `thread_title_updated`                                                                                                                                 |
+| Subagents    | `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`                                                                                                                                                           |
+| Memory       | `om_observation_start`, `om_observation_end`, `om_observation_failed`, `om_reflection_start`, `om_reflection_end`, `om_reflection_failed`, `om_buffering_start`, `om_buffering_end`, `om_buffering_failed`, `om_model_changed`, `om_activation`, `om_status`, `om_thread_title_updated` |
+| Workspace    | `workspace_ready`, `workspace_error`, `workspace_status_changed`                                                                                                                                                                                                                        |
+| Notification | `notification`, `notification_summary`, `info`, `error`                                                                                                                                                                                                                                 |
+
+A controller can also emit events the SDK doesn't type, so comparing `event.type` to a literal doesn't narrow the union. Narrow with `isKnownAgentControllerEvent(event)` to get a typed payload.
+
 ## Related
 
 - [Agents](https://mastra.ai/docs/agents/overview)

package/.docs/docs/harness/background-tasks.md

@@ -275,7 +275,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 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.
+When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. Once the resume payload is available, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })` to continue immediately. The resumed background task completes and adds its result to the message list before the agent runs a follow-up turn on the same SSE connection. To drive the resume out of band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly. Its result is still written into the thread for the next user turn.
 
 ### Re-registering the executor on resume
 

package/.docs/docs/harness/durable-agents.md

@@ -70,7 +70,7 @@ A durable agent adds three layers on top of a regular agent:
 
 1. **Workflow execution**: `stream()` serializes the messages and options into a workflow input, then triggers the agentic loop inside a durable workflow. The workflow runs the same loop as `Agent.stream()` but each step can be memoized and replayed.
 
-2. **PubSub streaming**: As the loop runs, chunks are published to a PubSub topic keyed by the run ID. The caller subscribes to this topic and pipes chunks into a `ReadableStream`. If the caller disconnects and reconnects, missed chunks are replayed from the cache.
+2. **PubSub streaming**: The loop publishes chunks to a PubSub topic keyed by the run ID. The caller subscribes to that topic and pipes the chunks into a `ReadableStream`, while the cache replays any chunks missed during a disconnect.
 
 3. **Cache layer**: An optional cache (in-memory by default, Redis or another backend in production) stores published events so that a late subscriber can catch up.
 

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

@@ -14,14 +14,13 @@ In Mastra, harness refers to a set of capabilities for managing an agent beyond
 
 Choose a starting point based on what the agent needs. You may use one capability or several.
 
-| If you want to                                                                        | Start here                                                                            | Why                                                                                     |
-| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| Keep a run available through client disconnects or server restarts                    | [Durable Agents](https://mastra.ai/docs/harness/durable-agents)                       | Persist run state and let clients reconnect to its stream.                              |
-| Run slow tools, workflows, or subagents without blocking                              | [Background Tasks](https://mastra.ai/docs/harness/background-tasks)                   | Finish work asynchronously and return its result to the agent.                          |
-| Keep an agent working until it reaches an objective                                   | [Goals](https://mastra.ai/docs/harness/goals)                                         | Evaluate a thread-scoped objective until it's complete or reaches its run budget.       |
-| Start work automatically at recurring times                                           | [Schedules](https://mastra.ai/docs/harness/schedules)                                 | Start isolated runs or send prompts into an existing thread on a cron schedule.         |
-| Add context, redirect active work, or wake an idle thread                             | [Signals](https://mastra.ai/docs/harness/signals)                                     | Deliver input now or hold it for the next turn.                                         |
-| React to changes in GitHub, Slack, continuous integration, or another external system | [Signal Providers](https://mastra.ai/docs/harness/signal-providers)                   | Track subscriptions and forward matching events to agent threads.                       |
-| Build an interactive product with sessions, modes, state, approvals, and events       | [AgentController](https://mastra.ai/docs/harness/agent-controller)                    | Host isolated sessions around a shared agent runtime.                                   |
-| Let users steer, queue follow-up work, or stop an interactive run                     | [AgentController](https://mastra.ai/docs/harness/agent-controller)                    | Expose run controls through each session.                                               |
-| Give an agent files, a shell, and the defaults a coding agent needs                   | [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) | Build a standard agent with a workspace, task tracking, and retries already configured. |
+| If you want to                                                                                                                            | Start here                                                                            | Why                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Keep a run available through client disconnects or server restarts                                                                        | [Durable Agents](https://mastra.ai/docs/harness/durable-agents)                       | Persist run state and let clients reconnect to its stream.                              |
+| Run slow tools, workflows, or subagents without blocking                                                                                  | [Background Tasks](https://mastra.ai/docs/harness/background-tasks)                   | Finish work asynchronously and return its result to the agent.                          |
+| Keep an agent working until it reaches an objective                                                                                       | [Goals](https://mastra.ai/docs/harness/goals)                                         | Evaluate a thread-scoped objective until it's complete or reaches its run budget.       |
+| Start work automatically at recurring times                                                                                               | [Schedules](https://mastra.ai/docs/harness/schedules)                                 | Start isolated runs or send prompts into an existing thread on a cron schedule.         |
+| Add context, redirect active work, or wake an idle thread                                                                                 | [Signals](https://mastra.ai/docs/harness/signals)                                     | Deliver input now or hold it for the next turn.                                         |
+| React to changes in GitHub, Slack, continuous integration, or another external system                                                     | [Signal Providers](https://mastra.ai/docs/harness/signal-providers)                   | Track subscriptions and forward matching events to agent threads.                       |
+| Build an interactive product with sessions, modes, state, approvals, and events, or let users steer, queue follow-up work, and stop a run | [AgentController](https://mastra.ai/docs/harness/agent-controller)                    | Host isolated sessions around a shared agent runtime, each with its own run controls.   |
+| Give an agent files, a shell, and the defaults a coding agent needs                                                                       | [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) | Build a standard agent with a workspace, task tracking, and retries already configured. |

package/.docs/docs/harness/schedules.md

@@ -8,7 +8,7 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/harness/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt either as a [signal](https://mastra.ai/docs/harness/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring work such as daily summaries and periodic checks, including scheduled nudges into a conversation.
 
 Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 

package/.docs/docs/harness/signal-providers.md

@@ -130,7 +130,7 @@ Mastra calls `poll()` on the `pollInterval` with all active subscriptions. It sk
 
 Use polling when the external source doesn't push events to your app. Set `pollInterval` and override `poll(subscriptions)`. Each subscription includes the thread target and the external resource id to inspect.
 
-Use webhooks when the external source can call your app. Override `handleWebhook(request)`, parse the payload, find matching subscriptions, and call `notify()` for each match.
+Use webhooks when the external source can call your app. Override `handleWebhook(request)` to parse the payload, then find matching subscriptions and call `notify()` for every match.
 
 ```typescript
 import { SignalProvider } from '@mastra/core/signals'

package/.docs/docs/harness/signals.md

@@ -8,7 +8,7 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle or drops input into the running agent loop, or alternatively queues input for the next turn.
+Signals let you interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra wakes an idle agent or delivers input to its running loop; alternatively, it queues the input for the next turn.
 
 Use message APIs for user-authored input. Use `sendSignal()` for lower-level system context, such as background task notifications, policy reminders, or processor-generated context.
 

package/.docs/docs/index.md

@@ -239,7 +239,7 @@ Templates: [GitHub PR Code Review](https://mastra.ai/templates/github-pr-code-re
 <details>
 **Sales and go-to-market workflows**
 
-Turn customer conversations into structured tasks, generate investment memos, or automate outreach sequences.
+Turn customer conversations into structured tasks or generate investment memos. You can also automate outreach sequences.
 
 Used by [Kestral](https://mastra.ai/blog/kestral), [Orange Collective](https://mastra.ai/blog/orange-collective-vc-operating-system), [WorkOS](https://mastra.ai/blog/workos-teaching-mastra)
 

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

@@ -42,17 +42,17 @@ A local `.env` file is optional. Environment variables stored on the platform ar
    Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)
    ```
 
-   Accept the prompt and provisioning takes a few seconds — the database's connection variables are injected into your deploys automatically, with nothing to copy into an `.env` file. Decline it, or run in a non-interactive shell (CI, `--yes`), and the CLI falls back to the previous behavior: it prints the exact command to run yourself.
+   Accept the prompt, and provisioning takes a few seconds. The database's connection variables are injected into your deploys automatically, so you don't need to copy them into an `.env` file. If you decline the prompt or use a non-interactive shell (CI, `--yes`), the CLI falls back to printing the exact command for you to run.
 
    ```bash
    mastra env db create production --kind turso
    ```
 
-   The environment slug (`production` above) matches the environment the CLI would have deployed to — this is important because `mastra env db create` requires an environment argument in non-interactive shells when the project has more than one environment.
+   The environment slug (`production` above) matches the environment the CLI would have deployed to. The `mastra env db create` command requires an environment argument in non-interactive shells when the project has more than one environment.
 
-   Preflight also catches database URLs that point at your local machine. A `.env` file with `REDIS_URL=redis://localhost:6379` works during development, but the deployed server can't reach your laptop — so the CLI warns and offers the same managed provisioning. If you decline, the deploy continues with your value as-is; if you accept, the managed database's connection variables take precedence at deploy time while your local `.env` keeps working for development.
+   Preflight also catches database URLs that point at your local machine. A `.env` file with `REDIS_URL=redis://localhost:6379` works during development, but the deployed server can't reach your laptop. The CLI therefore warns and offers the same managed provisioning. If you decline, the deploy continues with your value as-is; if you accept, the managed database's connection variables take precedence at deploy time while your local `.env` keeps working for development.
 
-   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), it can't offer the inline fix — guard the path with an environment variable first so the file is only used during local development:
+   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), it can't offer the inline fix. Guard the path with an environment variable first so the file is only used during local development:
    >
    > ```ts
    > new LibSQLStore({
@@ -69,7 +69,7 @@ A local `.env` file is optional. Environment variables stored on the platform ar
 
    > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.
 
-Each deploy replaces the running server process, which affects agent turns that are still streaming when the new version goes live. Because Mastra Platform doesn't currently provide a configurable or guaranteed termination grace period, don't rely on a raised `server.drainTimeout` for turns that may run longer than the default drain window. Use [durable agents](https://mastra.ai/docs/harness/durable-agents) with persistent storage and cache when turns must survive a deploy, or handle an interrupted stream in the client. See [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server) for the available strategies.
+Replacing the running server process during each deploy can interrupt agent turns that are still streaming when the new version goes live because Mastra Platform doesn't currently let you configure or rely on guaranteed extra time before termination. Don't rely on a raised `server.drainTimeout` for turns that may outlast the default drain window. Use [durable agents](https://mastra.ai/docs/harness/durable-agents) with persistent storage and cache when turns must survive a deploy, or handle an interrupted stream in the client. The available strategies are documented in [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server).
 
 The first deploy writes a `.mastra-project.json` file linking your directory to the platform project. Commit it so later deploys, CI runs, and [`mastra env`](https://mastra.ai/docs/mastra-platform/environments) commands target the same project without extra flags.
 
@@ -93,7 +93,7 @@ Pass `--region` when a deploy creates a new environment to control where it runs
 mastra deploy --env production --region eu
 ```
 
-The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically, and observability data is routed to the ingest region that matches the environment's residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the full list of supported regions, database placement, and observability co-location.
+The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically, and observability data is routed to the ingest region that matches the environment's residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the full list of supported regions and database placement, along with observability co-location.
 
 ## Preflight checks
 
@@ -151,7 +151,7 @@ Projects that depend on packages from a private registry install them during the
    //npm.pkg.github.com/:_authToken=${NPM_TOKEN}
    ```
 
-   Keep the `${NPM_TOKEN}` reference literal. The package manager resolves it at install time, so the token itself never lands in your repository.
+   Keep the `${NPM_TOKEN}` reference literal. The package manager resolves it at install time, so the token itself is never written to your repository.
 
 3. Deploy as usual:
 
@@ -229,14 +229,14 @@ The deploy log is the source of truth: the legacy pipeline prints a deprecation
    Check whether this project is ready for the Mastra Platform environment pipeline.
 
    1. Find the installed version of `@mastra/core` (check package.json and the
-      lockfile for the version that actually resolved, not just the range).
-   2. If it is >= 1.44.0, tell me I'm good — no further action needed.
-   3. If it is < 1.44.0:
+      lockfile for the version that actually resolved, rather than only the range).
+   2. If it's >= 1.44.0, tell me I'm good. No further action is needed.
+   3. If it's < 1.44.0:
       a. Fetch the `@mastra/core` changelog from
          https://github.com/mastra-ai/mastra/blob/main/packages/core/CHANGELOG.md
          and read every entry between my installed version and the latest release.
       b. Scan my project (agents, workflows, tools, memory, storage, deployers,
-         telemetry — anywhere `@mastra/core`, `@mastra/*`, or `mastra` is imported)
+         telemetry, anywhere `@mastra/core`, `@mastra/*`, or `mastra` is imported)
          and list every Mastra API surface I actually use.
       c. For each used API, cross-reference the changelog and produce a table of:
          API I use → breaking change → severity (breaks build / breaks runtime /
@@ -248,11 +248,11 @@ The deploy log is the source of truth: the legacy pipeline prints a deprecation
          versions, then run typecheck and tests. Report anything still failing.
    4. Search my scripts, package.json, Dockerfiles, and CI config for
       `mastra server deploy` and `mastra studio deploy`. Replace each
-      occurrence with `mastra deploy` — this is the unified command required
+      occurrence with `mastra deploy`. This is the unified command required
       by the environment pipeline.
 
-   Do not restructure my CI, provision new infra, or change my environment
-   variable values — only the Mastra usage in my code and the deploy command
+   don't restructure my CI, provision new infra, or change my environment
+   variable values. Change only the Mastra usage in my code and the deploy command
    itself.
    ```
 
@@ -264,7 +264,7 @@ The deploy log is the source of truth: the legacy pipeline prints a deprecation
    + mastra deploy
    ```
 
-   `mastra deploy` builds once and deploys both the server and the Studio UI shell for the target environment. Any recent `mastra` CLI supports it. If yours doesn't, upgrade with `npm install -g mastra@latest`.
+   `mastra deploy` builds once and deploys both the server and the Studio UI shell for the target environment. It's supported by every recent `mastra` CLI; otherwise, upgrade with `npm install -g mastra@latest`.
 
 3. Deploy once. Your project is auto-adopted onto the environment pipeline and the `production` environment is created on first deploy. See [Environments](https://mastra.ai/docs/mastra-platform/environments) for the full model.
 

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

@@ -32,7 +32,7 @@ mastra deploy --env staging
 mastra env create eu-preview --type preview --region eu
 ```
 
-Each project has a single `production` environment, created by your first deploy. The region is fixed at creation. Databases attached to an environment are placed near the environment's region automatically, and observability data is routed to the ingest region for the matching residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the supported regions, database placement, and observability co-location. The number of environments per project depends on your plan.
+Each project has a single `production` environment, created by your first deploy. The region is fixed at creation. Attached databases are placed near the environment automatically, while observability data goes to the ingest region for the matching residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for supported regions and database placement, along with observability co-location. The number of environments per project depends on your plan.
 
 ## List environments
 
@@ -92,7 +92,7 @@ mastra env db create staging --kind turso --name my-project-staging-db
 
 If you'd rather share one database across every environment, attach it with `--shared` instead: `mastra env db create --kind turso --shared`.
 
-An environment can only use one database per provider. If the project already has a shared (`--shared`) database of the same provider, attaching an environment-scoped one is rejected with a variable name conflict, delete the shared database with `mastra env db delete` first. Deleting a database destroys it with the provider along with all of its data, so export anything you need to keep. See [Hosted databases](https://mastra.ai/docs/mastra-platform/database) for the full scoping model.
+Each environment can use one database per provider. An existing shared (`--shared`) database from the same provider creates a variable-name conflict with an environment-scoped database. Export any data you need to keep before running `mastra env db delete`, because this command destroys the shared provider database and its data. See [Hosted databases](https://mastra.ai/docs/mastra-platform/database) for the full scoping model.
 
 ## Delete an environment
 

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

@@ -65,7 +65,7 @@ Templates are the fastest way to get started. The platform creates a new reposit
 
 4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Gateway works on the first deploy.
 
-5. Select **Create project**. The platform creates the repository, writes a `.mastra-project.json` config file into it, provisions the managed databases, and triggers the initial Studio and Server deploys.
+5. Select **Create project**. The platform creates the repository with a `.mastra-project.json` config file, provisions its managed databases, then triggers the initial Studio and Server deploys.
 
 The initial deploy waits for managed databases to finish provisioning before it starts, so the template's first build sees the database connection environment variables.
 
@@ -109,7 +109,7 @@ Only one build per deploy target runs at a time. If a new push arrives while a b
 
 ### Manual GitHub deploys
 
-You can also trigger a deploy from the dashboard without pushing. Open the project, select **Deploy from GitHub**, pick the target (Studio, Server, or both) and a branch, and submit. The platform runs the deploy against the head commit of that branch and records the trigger as a **GitHub Workflow** deploy.
+You can also trigger a deploy from the dashboard without pushing. Open the project and select **Deploy from GitHub**. Choose the target (Studio, Server, or both) together with a branch, then submit. The platform runs the deploy against the head commit of that branch and records the trigger as a **GitHub Workflow** deploy.
 
 ## Track deploys
 

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

@@ -65,7 +65,7 @@ Observability ingest runs in two regions today: **US** (Iowa, `us-central1`) and
 | `pdx`, `iad`, `sfo`, `us` shorthand | US (Iowa)            |
 | `ams`, `eu` shorthand               | EU (Amsterdam)       |
 
-Compute and databases can be placed in more Railway and provider regions than observability supports, so co-location isn't perfect for every combination. A `us`-zone environment always sends telemetry to US ingest, and an `eu`-zone environment always sends telemetry to EU ingest, even if the underlying Railway region is a specific city not directly served by an ingest endpoint. Data residency is preserved at the zone level. Telemetry from an `eu` environment never crosses into the US.
+Railway and database providers offer more regions than observability ingest, so some combinations can't be fully co-located. Environments in the `us` zone always send telemetry to US ingest, while those in the `eu` zone use EU ingest. This routing applies even when the underlying Railway region is a city without a dedicated ingest endpoint. Data residency is preserved at the zone level. Telemetry from an `eu` environment never crosses into the US.
 
 ## Related
 

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

@@ -48,7 +48,7 @@ You get a stable API endpoint with environment variable management and custom do
 
    If you're not already authenticated, the CLI prompts you to log in. It stores your credentials locally and any subsequent CLI commands use these credentials.
 
-   The command runs `mastra build`, uploads the artifact, builds a Docker image, and deploys it. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
+   The command runs `mastra build` and uploads its artifact, then builds and deploys a Docker image. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
 
    > **Note:** Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically. On the first deploy, these seed the project if no env vars are set yet. After that, manage env vars through the web dashboard. Review and sanitize these files before first deploy to avoid uploading development-only or personal secrets.
 
@@ -60,7 +60,7 @@ You get a stable API endpoint with environment variable management and custom do
 
 ## Deploy lifecycle
 
-A deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). A project runs one build at a time. When multiple deploys queue up, the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
+Each project runs one build at a time as its deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). When multiple deploys queue up, the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
 
 ## Idle behavior
 
@@ -146,9 +146,9 @@ Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After y
    mastra auth tokens create ci-deploy
    ```
 
-   The CLI prints the token once. Copy it immediately — it cannot be retrieved again.
+   The CLI prints the token once. Copy it immediately because it can't be retrieved again.
 
-2. Add the token as a secret in your CI provider. In GitHub Actions, go to **Settings → Secrets and variables → Actions** and create a secret named `MASTRA_API_TOKEN`.
+2. Add the token as a secret in your CI provider. In GitHub Actions, go to **Settings → Secrets and variables → Actions** and create the `MASTRA_API_TOKEN` secret.
 
 3. Ensure your `.mastra-project.json` file is committed to the repository. The CLI reads the `organizationId` and `projectId` from this file to target the correct project during CI deploys.
 

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

@@ -70,7 +70,7 @@ To run the same codebase across `production` and `staging`, use [`mastra deploy
 
 ## Create a new project non-interactively
 
-`mastra deploy` can create a project on first run. If `--project <name>` doesn't match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with `--yes`, this is fully scriptable:
+On its first run, `mastra deploy` can create a project. When `--project <name>` doesn't match an existing project, the CLI treats the value as a new project name and creates it after confirmation. Add `--yes` to make this flow fully scriptable:
 
 ```bash
 mastra deploy --project "my-new-project" --yes

package/.docs/docs/mastra-platform/trace-intelligence.md

@@ -74,7 +74,7 @@ A theme can persist, disappear, split, merge, or return across snapshots. Treat
 
 ## Use the Trace Intelligence page
 
-1. Use the **Agent** selector to switch between agents with available analysis. An agent doesn't appear until its first themes are ready.
+1. Use the **Agent** selector to switch between agents after their first themes are ready and analysis becomes available.
 2. Select a theme in the flow to open its details and filter every column to traces containing that theme.
 3. The details panel shows the theme's description, its share of the snapshot, paged example summaries, and a trend of its trace count over time.
 4. Select **Clear filter** to restore the complete flow.