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

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

@@ -2,7 +2,7 @@
 
 # Scorers overview
 
-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.
+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.
 
@@ -114,7 +114,9 @@ export const contentWorkflow = createWorkflow({ ... })
 
 ## Trace evaluations
 
-In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows. This is particularly useful for analyzing past performance, debugging issues, or running batch evaluations.
+In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows.
+
+This is particularly useful for analyzing past performance or debugging issues, or alternatively running batch evaluations.
 
 > **Observability required:** To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for setup instructions.
 
@@ -131,11 +133,11 @@ const mastra = new Mastra({
 })
 ```
 
-Once registered, you can score traces interactively within Studio under the **Observability** section. Open Studio to manage scorers, review scores, and run experiments.
+Once registered, you can score traces interactively within Studio under the **Observability** section. Open Studio to manage scorers and review scores, plus run experiments.
 
 - **Scorers list**: Browse all registered scorers with their description, and the number of agents and workflows each scorer is attached to.
 - **Score results**: Select a scorer to see a paginated list of every score it has produced. Click a row to open the detail panel, which shows the score value, reason, input, output, and the prompts used by the judge. From this panel, save any result as a dataset item for future experiments.
-- **Agent Evaluate tab**: Open the Evaluate tab on any agent to attach or detach scorers, create or edit stored scorers inline, manage datasets, and run experiments. Experiment results display per-item scores alongside pass/fail status and version tags.
+- **Agent Evaluate tab**: Open the Evaluate tab on any agent to manage scorers and datasets. You can also run experiments there. Experiment results display per-item scores alongside pass/fail status and version tags.
 - **Trace scoring**: In the Observability section, run a scorer against any historical trace or span to evaluate past interactions. Filter scores by agent or workflow.
 
 ## Next steps

package/.docs/docs/evals/quick-checks.md

@@ -35,7 +35,7 @@ console.log(result.scores)
 
 ## Available checks
 
-Quick Checks fall into two categories:
+Quick Checks fall into these categories:
 
 ### Text checks
 
@@ -105,7 +105,7 @@ export const weatherAgent = new Agent({
   id: 'weather-agent',
   name: 'Weather Agent',
   instructions: 'Answer weather questions using the get_weather tool.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { get_weather: weatherTool },
   scorers: {
     noErrors: {

package/.docs/docs/getting-started/build-with-ai.md

@@ -8,7 +8,7 @@ To give your agent access to Mastra's documentation, we recommend using **skills
 
 ## Mastra skills
 
-Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Mastra skills contain setup instructions, best practices, CLI commands, and instructions on how to fetch up-to-date information from Mastra's documentation.
+Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things accurately and efficiently. Mastra skills contain setup instructions, best practices, CLI commands, and instructions on how to fetch up-to-date information from Mastra's documentation.
 
 To install all available Mastra skills, run the following command:
 
@@ -70,7 +70,9 @@ bun x skills update mastra
 
 ## Mastra CLI
 
-The [Mastra CLI](https://mastra.ai/reference/cli/mastra) gives your coding agent a direct line to your Mastra runtime. Agents can invoke agents, run workflows, execute tools, inspect memory, run evals, and query traces and logs.
+The [Mastra CLI](https://mastra.ai/reference/cli/mastra) gives your coding agent a direct line to your Mastra runtime.
+
+Agents can invoke other agents and run workflows. They can execute tools and inspect memory. They can also run evals or query traces and logs.
 
 **npm**:
 
@@ -107,7 +109,7 @@ Install the [Mastra skills](#mastra-skills) to teach your agent how to use the C
 
 ## Embedded package docs
 
-Mastra packages ship with embedded documentation in `dist/docs`. When you install a Mastra package, your AI agent can read these files directly from `node_modules` to understand the package's APIs and patterns.
+Mastra packages come with embedded documentation in `dist/docs`. When you install a Mastra package, your AI agent can read these files directly from `node_modules` to understand the package's APIs and patterns.
 
 Each `dist/docs` includes:
 
@@ -136,7 +138,7 @@ In addition to the [context files](#context-files) each documentation page also
 
 The `@mastra/mcp-docs-server` package provides direct local access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
 
-These tools are designed to help agents retrieve precise, task-specific information, whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
+These tools are designed to help agents retrieve precise, task-specific information, whether you're adding a feature to an agent or scaffolding a new project, or alternatively exploring how something works.
 
 If you're unable to use a local MCP server and need to connect to a remote server, use this URL: `https://mastra.mcp.kapa.ai`. You need to authenticate with your Google Account (only an anonymous ID is transmitted) for rate-limiting purposes. If possible, Mastra recommends using a local MCP server for better performance and reliability.
 

package/.docs/docs/getting-started/file-based-agents.md

@@ -12,7 +12,7 @@ This approach reduces glue code and makes the file system itself a direct repres
 
 You can build your entire project with file-based agents or combine this approach with agents and other primitives defined directly in code for incremental adoption.
 
-File-based agents have some limitations while in beta. Not every Mastra feature can be defined in a file yet, and they're not the best fit for dynamic configuration or runtime wiring. When needed, you can define agents and related primitives directly in code.
+File-based agents have some limitations while in beta. They don't support every Mastra feature yet. Runtime configuration and wiring are usually better defined directly in code, along with any related primitives.
 
 > **Note:** All Mastra documentation currently shows agents and primitives defined directly in code. File-based agents use the same underlying concepts and APIs, so the guidance elsewhere in the docs still applies. As file-based agents mature, more examples may use this structure where appropriate.
 
@@ -49,7 +49,7 @@ Create a folder at `src/mastra/agents/weather`. Inside, add a `config.ts` and an
 import { agentConfig } from '@mastra/core/agent'
 
 export default agentConfig({
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -80,7 +80,7 @@ Map each primitive or feature to its file convention:
 | [Logger](https://mastra.ai/reference/file-based-agents/logger)                   | `src/mastra/logger.ts`                                                                    |
 | [Server config](https://mastra.ai/reference/file-based-agents/server)            | `src/mastra/server.ts`                                                                    |
 | [Studio config](https://mastra.ai/reference/file-based-agents/studio)            | `src/mastra/studio.ts`                                                                    |
-| [Schedules](https://mastra.ai/docs/long-running-agents/schedules)                | Not yet file-based — create at runtime with `mastra.schedules.create()`                   |
+| [Schedules](https://mastra.ai/docs/long-running-agents/schedules)                | Not yet file-based, create at runtime with `mastra.schedules.create()`                    |
 
 ## Discovery lifecycle
 
@@ -88,7 +88,9 @@ File-based primitives are discovered by the Mastra bundler under `mastra dev` an
 
 After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent.
 
-Discovery is source-based and conservative. It skips symlinks, ignores test files, treats workflows and singleton project files as file-routed only when they have a default export, and ignores directories that aren't agent directories.
+Discovery is source-based and conservative.
+
+It skips symlinks, test files, and directories that aren't agent directories. Workflows and singleton project files are file-routed only when they have a default export.
 
 Start your app through the Mastra CLI so discovery runs:
 

package/.docs/docs/getting-started/manual-install.md

@@ -165,7 +165,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts
    ```
 
-   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
+   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.6-sol' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
 
    Add the following code:
 

package/.docs/docs/index.md

@@ -2,9 +2,9 @@
 
 # Get started
 
-Build AI agents your users actually depend on. Mastra is a TypeScript framework that gives you everything you need to prototype fast and ship with confidence. Create your first agent with a single command and start building.
+Mastra is a TypeScript framework for building AI agents and applications. Create your first agent with a single command and start building.
 
-**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.5`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.6-sol`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.
 
 Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
 
@@ -60,11 +60,11 @@ export const weatherTool = createTool({
 
 If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
 
-By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
 
 Short list of known model IDs are:
 
-- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `openai/gpt-5.6-sol`, `openai/gpt-5-mini`
 - `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
 - `google/gemini-2.5-flash`
 
@@ -92,7 +92,7 @@ export const weatherAgent = new Agent({
       Use the weatherTool to fetch current weather data.
 `,
   // Use a string in provider/model format, not provider:model or a provider object.
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { weatherTool },
 })
 ```
@@ -121,7 +121,7 @@ console.log(response.text)
 
 ## Quickstart
 
-Run this command to create a new project:
+Run this command to create a general-purpose agent harness with a local workspace, shell tools, memory, task tracking, web access, and recurring schedules. It also installs Mastra skills for your installed coding agent, so you can start prompting and editing it:
 
 **npm**:
 
@@ -162,89 +162,8 @@ Add Mastra to an existing project, or create a new app with your preferred frame
 
 For other frameworks, see the [framework integration guides](https://mastra.ai/guides/getting-started/next-js).
 
-## What you can build
+## Templates
 
-Here are some of the ways you can use Mastra:
+Browse [templates](https://mastra.ai/templates) for complete Mastra projects you can clone and adapt.
 
-<details>
-**Embed agents in your product**
-
-Add AI capabilities to your platform so your users can build or interact with agents.
-
-Used by [Replit](https://mastra.ai/blog/replitagent3), [Fireworks](https://mastra.ai/blog/fireworks-xml-prompting), [Medusa](https://mastra.ai/blog/medusa-ecommerce)
-
-</details>
-
-<details>
-**Customer-facing assistants**
-
-Build agents that handle inquiries, schedule appointments, send reminders, and answer questions via chat, WhatsApp, or voice.
-
-Used by [Vetnio](https://mastra.ai/blog/vetnio), [Lua](https://mastra.ai/blog/lua-scaling)
-
-Templates: [Docs Chatbot](https://mastra.ai/templates/docs-chatbot), [Slack Agent](https://mastra.ai/templates/slack-agent)
-
-</details>
-
-<details>
-**Internal copilots**
-
-Help employees work faster with AI that understands your domain—HR queries, clinical documentation, sales prep, or document generation.
-
-Used by [Factorial](https://mastra.ai/blog/factorial-case-study), [Counsel Health](https://mastra.ai/blog/counsel-health), [Cedar](https://mastra.ai/blog/cedar-case-study), [SoftBank](https://mastra.ai/blog/softbank-productivity-mastra-2025-08-20)
-
-Templates: [Chat with PDF](https://mastra.ai/templates/chat-with-pdf), [Google Sheet Analysis](https://mastra.ai/templates/google-sheets-analysis)
-
-</details>
-
-<details>
-**Data analysis agents**
-
-Let users query databases and dashboards in natural language. Connect to your data sources and return answers, charts, or reports.
-
-Used by [Index](https://mastra.ai/blog/index-case-study), [PLAID Japan](https://mastra.ai/blog/plaid-jpn-gcp-agents)
-
-Templates: [Chat with Database](https://mastra.ai/templates/text-to-sql), [CSV to Questions](https://mastra.ai/templates/csv-to-questions)
-
-</details>
-
-<details>
-**Content automation**
-
-Generate, transform, and manage structured content at scale—whether for a CMS, knowledge base, or documentation system.
-
-Used by [Sanity](https://mastra.ai/blog/sanity)
-
-Templates: [Chat with YouTube](https://mastra.ai/templates/chat-with-youtube), [Flash Cards from PDF](https://mastra.ai/templates/flash-cards-from-pdf)
-
-</details>
-
-<details>
-**DevOps & engineering automation**
-
-Automate deployments, debug production issues, manage infrastructure, and handle on-call workflows.
-
-Used by [StarSling](https://mastra.ai/blog/starsling)
-
-Templates: [GitHub PR Code Review](https://mastra.ai/templates/github-pr-code-review-agent), [Browser Agent](https://mastra.ai/templates/browsing-agent)
-
-</details>
-
-<details>
-**Sales & GTM workflows**
-
-Turn customer conversations into structured tasks, generate investment memos, or 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)
-
-Templates: [Customer Feedback Summarization](https://mastra.ai/templates/customer-feedback-summarization)
-
-</details>
-
-Browse [templates](https://mastra.ai/templates) for working examples.
-
-## Want to learn more?
-
-Here's a quick introduction:
-
-[YouTube video player](https://www.youtube-nocookie.com/embed/NosES9aJxCc)
+> **Note:** New to Mastra? Read [What is Mastra?](https://mastra.ai/docs/what-is-mastra) for an overview of the framework, its capabilities, and what you can build with it.

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

@@ -74,7 +74,7 @@ export const researchTool = createTool({
 
 ### Agent-level
 
-Use `backgroundTasks.tools` on the agent to opt in specific tools, override timeouts for individual tools, or run all background-eligible tools in the background. Use `disabled: true` to short-circuit background dispatch for the agent entirely.
+Use `backgroundTasks.tools` on the agent to opt in specific tools or override timeouts for individual tools, or alternatively run all background-eligible tools in the background. Use `disabled: true` to short-circuit background dispatch for the agent entirely.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -82,7 +82,7 @@ import { Agent } from '@mastra/core/agent'
 export const researcher = new Agent({
   id: 'researcher',
   instructions: 'You research topics and answer questions.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { researchTool, summarizeTool },
   backgroundTasks: {
     tools: {
@@ -106,7 +106,7 @@ When a tool is registered on an agent that has background tasks enabled, the mod
 }
 ```
 
-The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer — it's not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
+The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer, it's not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
 
 ### Resolution order
 
@@ -172,7 +172,7 @@ Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) fo
 
 ### Aggregate properties
 
-`stream()` with `untilIdle` returns a `MastraModelOutput` that looks like the one from a regular `stream()` call, but only `fullStream` spans the initial turn **and** any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
+`stream()` with `untilIdle` returns a `MastraModelOutput` that looks like the one from a regular `stream()` call, but `fullStream` alone spans the initial turn and any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
 
 ## Subagents in the background
 
@@ -184,7 +184,7 @@ import { Agent } from '@mastra/core/agent'
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'Coordinate research and writing using the available agents.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: { researchAgent, writingAgent },
   backgroundTasks: {
     tools: {
@@ -260,7 +260,7 @@ export const reviewTool = createTool({
 })
 ```
 
-The first invocation of `execute` sees `resumeData === undefined` and calls `suspend`. After the task is resumed, the runtime restarts the tool with `resumeData` populated; the `if` branch falls through and the tool returns its real result.
+The first invocation of `execute` sees `resumeData === undefined` and calls `suspend`. After the task is resumed, the runtime restarts the tool with `resumeData` populated. The `if` condition is false, so the tool returns its real result.
 
 To resume the task once an approval arrives:
 
@@ -273,19 +273,19 @@ 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 lands in 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, 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.
 
 ### Re-registering the executor on resume
 
-The manager keeps tool executors in process memory. If the process restarts while a task is suspended, the executor closure is gone — the caller of `resume()` must re-register it first via `manager.registerTaskContext(taskId, ...)`. Tasks dispatched and resumed inside the same process don't need this.
+The manager keeps tool executors in process memory. If the process restarts while a task is suspended, the executor closure is gone, the caller of `resume()` must re-register it first via `manager.registerTaskContext(taskId, ...)`. Tasks dispatched and resumed inside the same process don't need this.
 
 ### Cancelling a suspended task
 
-`manager.cancel(taskId)` works against suspended tasks the same way it works for running ones: the row flips to `cancelled`, the workflow snapshot is cleaned up, and a `task.cancelled` event fires.
+`manager.cancel(taskId)` works against suspended tasks the same way it works for running ones. The row changes to `cancelled` and the workflow snapshot is cleaned up. A `task.cancelled` event then fires.
 
 ## Lifecycle callbacks
 
-Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their respective outcomes:
+Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their outcomes:
 
 - Tool-level `background.onComplete` / `onFailed`: scoped to one tool.
 - Agent-level `backgroundTasks.onTaskComplete` / `onTaskFailed`: scoped to all tasks dispatched by this agent.

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

@@ -31,7 +31,7 @@ const agent = new Agent({
   id: 'researcher',
   name: 'Researcher',
   instructions: 'You research topics thoroughly.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 export const durableResearcher = createDurableAgent({ agent })
@@ -95,7 +95,7 @@ import { createDurableAgent } from '@mastra/core/agent/durable'
 const agent = new Agent({
   id: 'helper',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 export const durableHelper = createDurableAgent({ agent })
@@ -112,7 +112,7 @@ import { createEventedAgent } from '@mastra/core/agent/durable'
 const agent = new Agent({
   id: 'writer',
   instructions: 'You write articles.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 export const eventedWriter = createEventedAgent({ agent })
@@ -132,7 +132,7 @@ const inngest = new Inngest({ id: 'my-app' })
 const agent = new Agent({
   id: 'analyst',
   instructions: 'You analyze data.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 export const inngestAnalyst = createInngestAgent({ agent, inngest })
@@ -223,10 +223,51 @@ Resume the suspended run after approval:
 await durableAgent.resume(runId, { approved: true })
 ```
 
+## Crash recovery
+
+If the server process crashes while a durable agent run is in progress, that run remains in `running` status in storage with no automatic retry. On the next server start you can re-drive these orphaned runs so they pick up where they left off.
+
+### Automatic recovery
+
+Set `recovery.durableAgents` to `'auto'` in the Mastra config. The deployer calls `recoverAllDurableAgents()` on boot, right after restarting active workflow runs:
+
+```typescript
+export const mastra = new Mastra({
+  agents: { myAgent: durableAgent },
+  storage: new PostgresStore({ connectionString: process.env.DATABASE_URL! }),
+  recovery: { durableAgents: 'auto' },
+})
+```
+
+On startup, this discovers every registered durable agent with runs stuck in `running` status and re-drives them from the last persisted snapshot.
+
+> **Warning:** Recovery re-runs the agentic loop from the last snapshot, which re-issues LLM calls (real cost) and re-executes tool calls. Make sure your tools are idempotent before enabling automatic recovery.
+
+### Manual recovery
+
+If you need finer control — for example gating recovery behind a leader election or running it on a schedule — call the methods directly:
+
+```typescript
+// Recover all durable agents
+const result = await mastra.recoverAllDurableAgents()
+console.log(`Recovered ${result.recovered} runs (${result.succeeded} ok, ${result.failed} failed)`)
+
+// Recover a specific agent
+const agentResult = await durableAgent.recoverActiveRuns()
+
+// Recover a single known run
+await durableAgent.recoverActiveRuns({ runId: 'run-abc-123' })
+```
+
+### Multi-instance deployments
+
+There is no distributed lease or lock yet. In multi-replica deployments, every replica that starts with `recovery.durableAgents: 'auto'` will race to recover the same runs. For now, either gate recovery behind your own leader election or run it from a single replica.
+
 ## Related
 
 - [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent)
 - [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent)
 - [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest)
-- [Agent overview](https://mastra.ai/docs/agents/overview)
+- [Agent overview](https://mastra.ai/docs/agents/overview)
+- [Worker overview](https://mastra.ai/docs/deployment/workers)

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

@@ -6,7 +6,9 @@
 
 > **Beta:** The Goals feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
+A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted.
+
+The objective is persisted in thread state, so it survives reloads and is evaluated in-loop, even when a new message arrives in the middle of an already-running turn.
 
 Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents): an LLM-as-judge scores the agent's output each iteration and gates the loop. The difference is that a goal is **durable** (stored in thread state, not passed per call) and is set and updated through `Agent` methods rather than per-`stream()` options.
 
@@ -22,7 +24,7 @@ For a one-off completion check within a single `stream()` call, use [`isTaskComp
 
 ## Quickstart
 
-Goals require a configured [storage](https://mastra.ai/docs/storage/overview) backend and a memory-backed thread. Add a `goal` config to the agent — a judge model is required for the goal to do anything — then set an objective for a thread:
+Goals require a configured [storage](https://mastra.ai/docs/storage/overview) backend and a memory-backed thread. Add a `goal` config to the agent, a judge model is required for the goal to do anything, then set an objective for a thread:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -31,7 +33,7 @@ const worker = new Agent({
   id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory,
   goal: {
     judge: 'openai/gpt-5-mini',
@@ -51,19 +53,21 @@ const stream = await worker.stream('Start working on the goal', {
 })
 ```
 
-The `goal` config auto-registers the state-signal projection, so the model always sees the current objective as `<current-objective>` in its context — no extra setup needed.
+The `goal` config auto-registers the state-signal projection, so the model always sees the current objective as `<current-objective>` in its context without extra setup.
 
 ## How the goal step works
 
 A goal step runs inside the agentic execution loop, right after `isTaskComplete`. On a real candidate answer it scores the conversation against the objective and gates the loop:
 
-- **Not satisfied, budget remaining** → the loop continues; per-evaluation feedback is injected so the agent iterates.
+- **Not satisfied, budget remaining** → the loop continues. Per-evaluation feedback is injected so the agent iterates.
 - **Satisfied** → the loop stops and the objective is marked `done`.
 - **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops and the objective is marked `paused`. Raise `maxRuns`, then resume the objective to continue.
 
-The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations — the same gating as `isTaskComplete`.
+The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations, the same gating as `isTaskComplete`.
+
+**The judge model is the activation switch.** If no judge resolves (neither the per-objective override nor the agent's `goal.judge`), the goal step performs no scoring or budget consumption and emits no `goal` chunk.
 
-**The judge model is the activation switch.** If no judge resolves (neither the per-objective override nor the agent's `goal.judge`), the goal step does nothing: no scoring, no budget consumed, no `goal` chunk. Effective settings resolve as per-objective record value → agent `goal` config → built-in default (`maxRuns` `50`, a default judge prompt).
+Effective settings resolve as per-objective record value → agent `goal` config → built-in default (`maxRuns` `50`, a default judge prompt).
 
 By default the step uses a built-in LLM-as-judge scorer that returns `1` when the objective is achieved and `0` otherwise. Supply your own scorer with `goal.scorer` to customize judging.
 
@@ -72,7 +76,7 @@ const worker = new Agent({
   id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory,
   goal: {
     // A resolver function lets you inject provider credentials and read the
@@ -109,6 +113,6 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `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
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents): `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

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

@@ -25,7 +25,7 @@ const pinger = new Agent({
   id: 'pinger',
   name: 'Pinger',
   instructions: 'Report the current system status in one sentence.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 const mastra = new Mastra({
@@ -136,7 +136,7 @@ await mastra.schedules.create({
 })
 ```
 
-Workflow schedules created this way are independent of the declarative `schedule` field on `createWorkflow` — see [scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for the declarative form and Studio views.
+Workflow schedules created this way are independent of the declarative `schedule` field on `createWorkflow`, see [scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for the declarative form and Studio views.
 
 ### Custom IDs
 
@@ -187,7 +187,7 @@ The hooks are:
 
 - `prepare`: runs before the fire. Return an object to override fire-time parameters such as `prompt` or `threadId`, `null` to skip the fire, or `undefined` to use the stored defaults.
 - `onFinish`: runs once per trigger that reached a non-error, non-abort terminal state.
-- `onError`: runs when `prepare`, the signal, or the agent run threw.
+- `onError`: runs after a failure in `prepare` or the signal. It also runs when the agent run fails.
 - `onAbort`: runs when the run was aborted mid-stream.
 
 Every hook context includes `agentId` (the agent the schedule fired for) alongside `schedule` and `trigger`.

package/.docs/docs/long-running-agents/signal-providers.md

@@ -14,7 +14,7 @@ Use a signal provider when an external system produces events that an agent shou
 
 - The source emits events tied to a resource a thread cares about, such as a pull request, a channel, or a build.
 - You want one place that tracks which threads watch which external resources.
-- You want to receive events by polling, by webhook, or both.
+- You want to receive events by polling or by webhook, or alternatively both.
 
 If you only need to push a one-off event into a thread, call [`agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent) directly instead.
 
@@ -28,7 +28,9 @@ A signal provider combines three capabilities:
 - **Ingestion:** You override `poll()` for pull-based sources or `handleWebhook()` for push-based sources.
 - **Delivery:** When an event matches a subscription, call the protected `notify()` helper to forward a notification signal to the connected agent's thread.
 
-Register a provider by passing it to an agent. The agent connects the provider, starts polling if a `pollInterval` is set, and merges any processors or tools the provider exposes.
+Register a provider by passing it to an agent.
+
+The agent connects the provider and starts polling when a `pollInterval` is set. It also merges any processors or tools exposed by the provider.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -38,7 +40,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Help the user triage updates.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   signals: [new CiSignals()],
 })
 ```
@@ -111,7 +113,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Help the user triage CI updates.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   signals: [ciSignals],
 })
 
@@ -181,7 +183,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Help the user triage updates.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   signals: [webhooks],
 })
 
@@ -208,7 +210,7 @@ export const devAgent = new Agent({
   id: 'dev-agent',
   name: 'Dev Agent',
   instructions: 'Help triage pull request activity.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   signals: [new GithubSignals()],
 })
 ```