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

package/.docs/reference/agents/channels.md

@@ -17,7 +17,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You are a helpful support assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       slack: createSlackAdapter(),
@@ -70,7 +70,7 @@ const agent = new Agent({
   id: 'example',
   name: 'Example',
   instructions: '...',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       discord: {
@@ -110,7 +110,7 @@ const agent = new Agent({
 
 `toolDisplay` controls how tool calls render in chat. The default `'cards'` posts a "Running…" card per tool and edits it with the result, matching the behavior in earlier versions. `'text'` is the same lifecycle but without rich Block Kit, useful for platforms that don't render cards well.
 
-`'timeline'` and `'grouped'` stream tool state as inline `task_update` chunks alongside the agent's text. These modes require `streaming: true` and rely on the chat adapter to render the chunks. Slack supports both natively; other adapters may render a placeholder until they ship support. If `streaming` is disabled, the channel logs a one-time warning and falls back to `'cards'`.
+`'timeline'` and `'grouped'` stream tool state as inline `task_update` chunks alongside the agent's text. These modes require `streaming: true` and rely on the chat adapter to render the chunks. Slack supports both natively; other adapters may render a placeholder until they add support. If `streaming` is disabled, the channel logs a one-time warning and falls back to `'cards'`.
 
 `'hidden'` executes tools silently. Only the typing status indicates work in progress.
 
@@ -126,7 +126,7 @@ const agent = new Agent({
   id: 'streaming-agent',
   name: 'Streaming Agent',
   instructions: '...',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       slack: {
@@ -154,7 +154,7 @@ const agent = new Agent({
   id: 'custom-typing-agent',
   name: 'Custom Typing Agent',
   instructions: '...',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       discord: {
@@ -187,7 +187,7 @@ const agent = new Agent({
   id: 'custom-handler-agent',
   name: 'Custom Handler Agent',
   instructions: '...',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       slack: createSlackAdapter(),
@@ -216,19 +216,35 @@ type ChannelHandler = (
   thread: Thread,
   message: Message,
   defaultHandler: (thread: Thread, message: Message) => Promise<void>,
-  ctx?: ChannelHandlerContext,
+  ctx: ChannelHandlerContext,
 ) => Promise<void>
+
+type ChannelHandlerContext = {
+  mastra?: Mastra
+  requestContext: RequestContext
+}
+```
+
+`ctx.mastra` is the resolved `mastra` instance, so a handler can reach storage or other registered primitives without being passed an external accessor:
+
+```typescript
+onDirectMessage: async (thread, message, defaultHandler, ctx) => {
+  const store = await ctx.mastra?.getStorage()?.getStore('memory')
+  await defaultHandler(thread, message)
+}
 ```
 
-`ctx` carries the resolved `mastra` instance, so a handler can reach storage or other registered primitives without being passed an external accessor:
+`ctx.requestContext` is the [`RequestContext`](https://mastra.ai/docs/server/request-context) for the run this message is about to start, built fresh for every message. Write to it before calling `defaultHandler` and the value reaches the run, alongside the channel entries Mastra adds afterward:
 
 ```typescript
 onDirectMessage: async (thread, message, defaultHandler, ctx) => {
-  const store = await ctx?.mastra?.getStorage()?.getStore('memory')
+  ctx.requestContext.set('locale', 'en-GB')
   await defaultHandler(thread, message)
 }
 ```
 
+Anything the run reads from its request context can be decided per message this way, such as which user a platform sender maps to.
+
 ## Resource ID resolution
 
 By default a channel thread's memory `resourceId` is `${platform}:${message.author.userId}`. The sender owns the memory, scoped per platform. For apps with a shared identity, such as single sign-on (SSO), this splits memory: the same user gets `feishu:user_123` in a Feishu DM but `user_123` on the web.
@@ -243,7 +259,7 @@ const agent = new Agent({
   id: 'sso-agent',
   name: 'SSO Agent',
   instructions: '...',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       slack: createSlackAdapter(),
@@ -272,9 +288,9 @@ The `ResolveResourceIdContext` passed to the function:
 
 ## Thread ID resolution
 
-By default a new channel thread gets a random UUID as its internal Mastra thread id. Pass `resolveThreadId` to pick the id yourself — for example, give the thread the same id as the session it belongs to, matching how your app names threads it creates itself.
+By default a new channel thread gets a random UUID as its internal Mastra thread id. Pass `resolveThreadId` to pick the id yourself: for example, give the thread the same id as the session it belongs to, matching how your app names threads it creates itself.
 
-The hook runs after `resolveResourceId`, so the resolved owner is available on the context. Like `resolveResourceId` it runs only when a new thread is created: reused threads keep their stored id and never call the hook. The returned id must be unique across the memory store — if it already belongs to an existing thread, Mastra logs a warning and uses a generated id instead so the existing thread is never overwritten. Return `ctx.defaultThreadId` to keep the built-in behavior.
+The hook runs after `resolveResourceId`, so the resolved owner is available on the context. Like `resolveResourceId` it runs only when a new thread is created: reused threads keep their stored id and never call the hook. The returned id must be unique across the memory store. If it already belongs to an existing thread, Mastra logs a warning and uses a generated id instead so the existing thread is never overwritten. Return `ctx.defaultThreadId` to keep the built-in behavior.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -284,7 +300,7 @@ const agent = new Agent({
   id: 'session-agent',
   name: 'Session Agent',
   instructions: '...',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   channels: {
     adapters: {
       slack: createSlackAdapter(),

package/.docs/reference/agents/durable-agent.md

@@ -17,7 +17,7 @@ const agent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 const durableAgent = createDurableAgent({ agent })
@@ -39,7 +39,7 @@ cleanup()
 
 ### Using the `durable` config flag
 
-Set `durable: true` on `AgentConfig` and the agent is automatically wrapped with `createDurableAgent` when it is attached to a `Mastra` instance. Use an object to forward advanced options such as `cache`, `pubsub`, `maxSteps`, or `cleanupTimeoutMs`.
+Set `durable: true` on `AgentConfig` and the agent is automatically wrapped with `createDurableAgent` when it's attached to a `Mastra` instance. Use an object to forward advanced options such as `cache`, `pubsub`, `maxSteps`, or `cleanupTimeoutMs`.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -49,7 +49,7 @@ const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   durable: true, // or: { maxSteps: 10, cleanupTimeoutMs: 60_000 }
 })
 
@@ -58,7 +58,7 @@ export const mastra = new Mastra({
 })
 ```
 
-`mastra.getAgent('myAgent')` returns the wrapped `DurableAgent`. Standalone agents (constructed but never registered on a `Mastra` instance) do not become durable; the wrapping is applied at registration.
+`mastra.getAgent('myAgent')` returns the wrapped `DurableAgent`. Standalone agents (constructed but never registered on a `Mastra` instance) don't become durable. The wrapping is applied at registration.
 
 ## `createDurableAgent(options)`
 
@@ -176,7 +176,7 @@ await output.text
 
 Returns: `Promise<DurableAgentStreamResult>`
 
-> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, don't call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup doesn't fire on suspended events.
+> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, don't call `cleanup()`. Let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup doesn't fire on suspended events.
 
 #### `prepare(messages, options?)`
 
@@ -204,6 +204,55 @@ interface PrepareResult {
 }
 ```
 
+### Recovery
+
+#### `recoverActiveRuns(options?)`
+
+Discovers runs stuck in `running` status for this agent and re-drives them from the last persisted snapshot. Recovers up to `options.limit` runs (default: 100). Returns a summary of what was recovered.
+
+```typescript
+const result = await durableAgent.recoverActiveRuns()
+// { recovered: [{ runId, status }], succeeded: 2, failed: 0 }
+```
+
+Pass a `runId` to recover a single known run:
+
+```typescript
+await durableAgent.recoverActiveRuns({ runId: 'run-abc-123' })
+```
+
+Returns:
+
+```typescript
+interface DurableAgentRecoverActiveRunsResult {
+  recovered: Array<{ runId: string; status: 'success' | 'failed'; error?: Error }>
+  succeeded: number
+  failed: number
+}
+```
+
+**options.runId** (`string`): Recover a specific run by ID. When set, discovery filters are ignored.
+
+**options.limit** (`number`): Maximum number of active runs to discover. Defaults to 100.
+
+**options.createdBefore** (`Date`): Only recover runs created before this date.
+
+#### `recover(runId, options?)`
+
+Recovers a single run by ID. Returns a streamable result with the same shape as `stream()`. Use this when you need to observe the recovery stream in real time.
+
+```typescript
+const { output, cleanup } = await durableAgent.recover('run-abc-123', {
+  onChunk: chunk => console.log(chunk),
+  onError: ({ error }) => console.error(error),
+})
+
+await output.text
+cleanup()
+```
+
+Returns: [`Promise<DurableAgentStreamResult>`](#durableagentstreamresult)
+
 ## Stream options
 
 `stream()` accepts a `DurableAgentStreamOptions` object. It supports the agent execution options below, plus lifecycle callbacks.

package/.docs/reference/agents/generate.md

@@ -387,7 +387,7 @@ const limitedResult = await agent.generate('Write a short poem about coding', {
 
 ### With memory
 
-Give your agent access to conversation history and persistence by configuring memory options. This allows the agent to remember previous interactions and maintain context across messages.
+Give your agent access to conversation history and persistence by configuring memory options. It allows the agent to remember previous interactions and maintain context across messages.
 
 ```ts
 const memoryResult = await agent.generate('Remember my favorite color is blue', {
@@ -436,7 +436,7 @@ console.log(response.text)
 
 ### Using `maxSteps`
 
-The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 5, but can be increased:
+The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step generates a response and executes any tool calls before processing the result. Limiting steps helps prevent infinite loops and reduce latency. It also controls token usage for agents that use tools. The default is 5, but can be increased:
 
 ```typescript
 const response = await agent.generate('Help me organize my day', {
@@ -462,7 +462,7 @@ const response = await agent.generate('Help me organize my day', {
 
 ### Using `onTitleGenerated`
 
-When `generateTitle` is enabled in memory options, title generation runs asynchronously after the response completes. Use `onTitleGenerated` to react when the title is ready — for example, to push it to the client via SSE.
+When `generateTitle` is enabled in memory options, title generation runs asynchronously after the response completes. Use `onTitleGenerated` to react when the title is ready, for example by pushing it to the client via SSE.
 
 ```typescript
 const response = await agent.generate('What is quantum computing?', {

package/.docs/reference/agents/generateLegacy.md

@@ -205,7 +205,7 @@ await agent.generateLegacy(
         sentiment: z.enum(['positive', 'negative', 'neutral']),
         confidence: z.number(),
       }),
-      model: 'openai/gpt-5.5',
+      model: 'openai/gpt-5.6-sol',
       errorStrategy: 'warn',
     },
     // Output processors for response validation

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

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

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

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

package/.docs/reference/agents/getLLM.md

@@ -12,7 +12,7 @@ await agent.getLLM()
 
 ```typescript
 await agent.getLLM({
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -33,7 +33,7 @@ await agent.getLLM({
 ```typescript
 await agent.getLLM({
   requestContext: new RequestContext(),
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 

package/.docs/reference/agents/getMetadata.md

@@ -31,7 +31,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You help customers with support requests.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   metadata: { type: 'support' },
 })
 
@@ -47,7 +47,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You help customers with support requests.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   metadata: ({ requestContext }) => ({
     type: 'support',
     tenant: requestContext.get('tenant'),

package/.docs/reference/agents/inngest-agent.md

@@ -22,7 +22,7 @@ const agent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 const durableAgent = createInngestAgent({ agent, inngest })

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

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

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

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

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

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

package/.docs/reference/agents/network.md

@@ -18,7 +18,7 @@ const agent = new Agent({
   id: 'network-agent',
   name: 'Network Agent',
   instructions: 'You are a network agent that can help users with a variety of tasks.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: {
     agent1,
     agent2,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -23,7 +23,7 @@ export const browserAgent = new Agent({
   name: 'Browser Agent',
   instructions: `You can browse the web. Use browser_snapshot to see the page structure,
 then interact with elements using their refs (e.g., @e5).`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   browser,
 })
 ```
@@ -107,7 +107,7 @@ Navigate to a URL.
 
 | Parameter   | Type                                            | Description                                     |
 | ----------- | ----------------------------------------------- | ----------------------------------------------- |
-| `url`       | `string`                                        | URL to navigate to                              |
+| `url`       | `string`                                        | URL to open                                     |
 | `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | When to consider navigation complete (optional) |
 | `timeout`   | `number`                                        | Navigation timeout in ms (optional)             |
 
@@ -358,7 +358,7 @@ Execute JavaScript in the page context. Use as an escape hatch when other tools
 
 ### `browser_screenshot`
 
-Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `browser_snapshot` when you only need text or structured data.
+Capture a screenshot of the current page as PNG (viewport by default. Set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `browser_snapshot` when you only need text or structured data.
 
 ```text
 // Viewport only (default)

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

@@ -26,7 +26,7 @@ const workspace = new Workspace({
 
 const browserAgent = new Agent({
   id: 'browser-agent',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   workspace,
   instructions: 'You are a web automation assistant.',
   memory: new Memory(),
@@ -227,6 +227,6 @@ browse skills install
 
 ## Related
 
-- [BrowserViewer guide](https://mastra.ai/docs/browser/browser-viewer) — setup and usage walkthrough
-- [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser) — base class API reference
-- [Workspace overview](https://mastra.ai/docs/workspace/overview) — workspace configuration
+- [BrowserViewer guide](https://mastra.ai/docs/browser/browser-viewer): Setup and usage walkthrough
+- [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class API reference
+- [Workspace overview](https://mastra.ai/docs/workspace/overview): Workspace configuration

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

@@ -24,7 +24,7 @@ export const browserAgent = new Agent({
   name: 'Browser Agent',
   instructions: `You can browse the web. Use browser_snapshot to see the page structure,
 then interact with elements using their refs (e.g., @e5).`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   browser,
 })
 ```

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

@@ -2,7 +2,7 @@
 
 # MastraBrowser class
 
-The `MastraBrowser` class is the abstract base class for browser automation providers. It defines the common interface for launching browsers, managing thread isolation, streaming screencasts, and handling input events.
+The `MastraBrowser` class is the abstract base class for browser automation providers. Its common interface covers browser launch and thread isolation, plus screencast streaming and input events.
 
 You don't instantiate `MastraBrowser` directly. Instead, use a provider implementation:
 
@@ -26,7 +26,7 @@ export const browserAgent = new Agent({
   id: 'browser-agent',
   name: 'Browser Agent',
   instructions: 'You can browse the web to find information.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   browser,
 })
 ```
@@ -135,7 +135,7 @@ const hasSession = browser.hasThreadSession('thread-123')
 
 #### `closeThreadSession(threadId)`
 
-Closes a specific thread's browser session. For 'thread' scope, this closes that thread's browser instance. For 'shared' scope, this clears the thread's state.
+Closes a specific thread's browser session. With 'thread' scope, it closes that thread's browser instance. With 'shared' scope, it clears the thread state.
 
 ```typescript
 await browser.closeThreadSession('thread-123')
@@ -145,7 +145,7 @@ await browser.closeThreadSession('thread-123')
 
 #### `getTools()`
 
-Returns the browser tools for use with agents. Each provider returns different tools based on its paradigm.
+Returns the browser tools for use with agents. Each provider returns different tools based on its model.
 
 ```typescript
 const tools = browser.getTools()