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

package/.docs/docs/agent-builder/access-control.md

@@ -4,7 +4,7 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-The Agent Builder ships with two supported roles: `admin` and `member`. Wire them through `Mastra.server.rbac`. Without an RBAC provider, every authenticated user has full Builder access; without authentication, the Builder is open to anyone who can reach the server.
+The Agent Builder includes with two supported roles: `admin` and `member`. Wire them through `Mastra.server.rbac`. Without an RBAC provider, every authenticated user has full Builder access; without authentication, the Builder is open to anyone who can reach the server.
 
 ## Roles
 
@@ -15,11 +15,11 @@ The Agent Builder ships with two supported roles: `admin` and `member`. Wire the
 
 ## Minimum permissions
 
-The Builder UI calls several resources on load, so a usable `member` role needs explicit grants on each. The Builder action layer (`/agent-builder/*`) is one resource; the data it reads and writes lives under separate resources.
+The Builder UI calls several resources on load, so a usable `member` role needs explicit grants on each. The Builder action layer (`/agent-builder/*`) is one resource. The data it reads and writes lives under separate resources.
 
 | Permission                            | Used for                                                                                                                                                    |
 | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent-builder:*`                     | Load Builder actions and run Builder workflows. The derived Builder actions are `agent-builder:read` and `agent-builder:execute`; the wildcard grants both. |
+| `agent-builder:*`                     | Load Builder actions and run Builder workflows. The derived Builder actions are `agent-builder:read` and `agent-builder:execute`. The wildcard grants both. |
 | `agents:read`, `agents:execute`       | List registered agents and chat with the Builder agent                                                                                                      |
 | `stored-agents:*`                     | List, view, create, and edit agents                                                                                                                         |
 | `stored-skills:*`                     | List, view, create, and edit stored skills                                                                                                                  |

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

@@ -50,7 +50,7 @@ new MastraEditor({
 - `name`: Display name shown in the Builder UI.
 - `createBrowser(config)`: Hydrates a stored browser config into a runtime `MastraBrowser`. This is where you inject runtime-only credentials (API keys, project IDs) that aren't stored in the agent snapshot.
 
-Browser classes ship as separate packages (e.g., `@mastra/stagehand`, `@mastra/agent-browser`). The provider entry is a plain object wrapping the class — register one entry per browser you want the Builder to expose to end users. See the [StorageBrowserRef reference](https://mastra.ai/reference/editor/storage-browser-ref) for the full `browser` field schema, including all `StorageBrowserConfig` options.
+Browser classes release as separate packages (e.g., `@mastra/stagehand`, `@mastra/agent-browser`). The provider entry is a plain object wrapping the class, register one entry per browser you want the Builder to expose to end users. See the [StorageBrowserRef reference](https://mastra.ai/reference/editor/storage-browser-ref) for the full `browser` field schema, including all `StorageBrowserConfig` options.
 
 ## Feature toggle
 

package/.docs/docs/agent-builder/channels.md

@@ -66,7 +66,7 @@ The Slack provider handles app creation, OAuth, slash commands, and message rout
 `SlackProvider` requires one environment variable and accepts one optional override:
 
 - `SLACK_APP_CONFIG_REFRESH_TOKEN` (required): The refresh token from your Slack app configuration tokens, available under **Your App Configuration Tokens** on [api.slack.com/apps](https://api.slack.com/apps). The refresh token doesn't expire, but the access tokens it issues rotate every 12 hours and are auto-persisted to `Mastra.storage`.
-- `baseUrl` (optional): The public URL Slack should send events and OAuth callbacks to. Defaults to the running Mastra server's host and port (for example, `http://localhost:4111` in local development). Pass `baseUrl` explicitly when the public URL differs from the server's resolved address — typically a tunnel for local development (`cloudflared tunnel --url http://localhost:4111`) or a deployed URL in production.
+- `baseUrl` (optional): The public URL Slack should send events and OAuth callbacks to. Defaults to the running Mastra server's host and port (for example, `http://localhost:4111` in local development). Pass `baseUrl` explicitly when the public URL differs from the server's resolved address: typically a tunnel for local development (`cloudflared tunnel --url http://localhost:4111`) or a deployed URL in production.
 
 ## Storage requirement
 

package/.docs/docs/agent-builder/configuration.md

@@ -4,7 +4,7 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-The Agent Builder is configured through `MastraEditor.builder`. Two top-level keys control its behavior: `features` toggles UI visibility and `configuration` pins admin-controlled defaults onto every new agent.
+The Agent Builder is configured through `MastraEditor.builder`. Top-level keys control its behavior: `features` toggles UI visibility and `configuration` pins admin-controlled defaults onto every new agent.
 
 ## Quickstart
 
@@ -55,7 +55,7 @@ new MastraEditor({
 })
 ```
 
-The shipping UI consumes these `AgentFeatures` keys: `tools`, `agents`, `workflows`, `scorers`, `skills`, `memory`, `variables`, `favorites`, `avatarUpload`, `model`, and `browser`. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full schema.
+The UI consumes these `AgentFeatures` keys: `tools`, `agents`, `workflows`, `scorers`, `skills`, `memory`, `variables`, `favorites`, `avatarUpload`, `model`, and `browser`. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full schema.
 
 ## Admin defaults
 
@@ -95,7 +95,7 @@ export const mastra = new Mastra({
 
 With no `configuration.agent.tools.allowed` set, both `weather-info` and `web-search` appear in the Builder's tool picker. End users can attach either tool to any agent they create.
 
-Entries match on `tool.id`, `Agent.id`, or `workflow.id` — the string the entity reports at runtime, not the export name.
+Entries match on `tool.id`, `Agent.id`, or `workflow.id`, the string the entity reports at runtime, not the export name.
 
 MCP tools work the same way: load them via `MCPClient.getTools()` and spread the result into the `tools` map.
 

package/.docs/docs/agent-builder/deploying.md

@@ -10,8 +10,8 @@ Production deployments swap the local primitives in the Quickstart for cloud-bac
 
 1. **EE license**: A valid `MASTRA_EE_LICENSE` so the server will start with the Builder enabled.
 2. **Hosted storage**: A shared store for agents, skills, runs, and memory.
-3. **Shared workspace filesystem**: Survives across instances; `local` is single-node only.
-4. **Cloud sandbox**: Runs agent commands safely; `local` is unsafe in shared environments.
+3. **Shared workspace filesystem**: Survives across instances. `local` is single-node only.
+4. **Cloud sandbox**: Runs agent commands safely. `local` is unsafe in shared environments.
 5. **Auth and RBAC**: Gates the Builder UI and `/agent-builder/*` routes.
 6. **Public base URL for channels**: Slack and other channel providers need a reachable URL.
 

package/.docs/docs/agent-builder/integrations.md

@@ -6,7 +6,7 @@
 
 Tool providers let Builder-created agents call tools from third-party apps such as Gmail, Slack, or GitHub. The Builder reuses the same tool providers as the editor, so any provider registered on `MastraEditor` is available in the Builder.
 
-This page covers what's specific to the Builder: setting up connections, choosing a connection scope, and managing connections. To register a provider and enable its toolkits, see [Tools](https://mastra.ai/docs/editor/tools).
+This page covers Builder-specific connection setup, scope selection, and management. To register a provider and enable its toolkits, see [Tools](https://mastra.ai/docs/editor/tools).
 
 ## Setup at a glance
 
@@ -14,7 +14,7 @@ To connect a toolkit like Gmail and use it from a Builder agent:
 
 1. [Register a tool provider](#register-a-tool-provider) on `MastraEditor` with your Composio API key.
 2. [Set up a Composio auth config](#set-up-a-composio-auth-config) for the toolkit and enable it.
-3. [Connect the toolkit](#connect-a-toolkit) from the Builder and complete the OAuth flow.
+3. In the Builder, [connect the toolkit](#connect-a-toolkit) and authorize the connection.
 4. [Choose a connection scope](#connection-scope) if the default author-owned account isn't what you want.
 
 The rest of this page covers each step in detail.
@@ -29,7 +29,7 @@ Before agents can use integration tools in the Builder:
 
 ## Register a tool provider
 
-The Builder reuses the editor's tool providers. Register each provider you want to expose on the `toolProviders` map of `MastraEditor`. Mastra ships providers for [Composio](https://composio.dev) and [Arcade](https://arcade.dev); add a provider by giving it a key and an instance.
+The Builder reuses the editor's tool providers. Register each provider you want to expose on the `toolProviders` map of `MastraEditor`. Mastra includes providers for [Composio](https://composio.dev) and [Arcade](https://arcade.dev). Add a provider by giving it a key and an instance.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -49,13 +49,13 @@ export const mastra = new Mastra({
 })
 ```
 
-Each provider's toolkits become available in the Builder once it's registered. Use `allowedToolkits` to restrict which toolkits the provider exposes — by slug, such as `gmail` or `googlecalendar`. Omit it to expose every toolkit the provider offers. To add another provider, import it and add another entry to `toolProviders`. For the full list of providers and their options, see [Tools — Integration providers](https://mastra.ai/docs/editor/tools).
+Each provider's toolkits become available in the Builder once it's registered. Use `allowedToolkits` to restrict which toolkits the provider exposes, by slug, such as `gmail` or `googlecalendar`. Omit it to expose every toolkit the provider offers. To add another provider, import it and add another entry to `toolProviders`. For the full list of providers and their options, see [Tools, Integration providers](https://mastra.ai/docs/editor/tools).
 
 `ComposioToolProvider` needs a Composio **project** API key (the `x-api-key` type from a project's settings in the [Composio dashboard](https://dashboard.composio.dev)). Store it in an environment variable, as shown with `COMPOSIO_API_KEY` above.
 
 ## Set up a Composio auth config
 
-Each toolkit a user can connect needs its own auth config in the [Composio dashboard](https://dashboard.composio.dev). An auth config defines how Composio authenticates with an app — its OAuth client, scopes, and credentials. Each toolkit needs its own because requirements vary by app: some share common OAuth methods, while others need extra setup. Without an enabled config, the connection flow fails.
+Each toolkit a user can connect needs its own auth config in the [Composio dashboard](https://dashboard.composio.dev). An auth config defines how Composio authenticates with an app, its OAuth client, scopes, and credentials. Each toolkit needs its own because requirements vary by app: some share common OAuth methods, while others need extra setup. Without an enabled config, the connection flow fails.
 
 1. Open the [Composio dashboard](https://dashboard.composio.dev) and select the toolkit you want to enable, for example **Gmail** or **GitHub**.
 2. Create an auth config for the toolkit and complete the app-specific setup. Composio's [auth config docs](https://docs.composio.dev/docs/authenticating-tools) cover the fields each app requires.
@@ -63,7 +63,7 @@ Each toolkit a user can connect needs its own auth config in the [Composio dashb
 
 Keep exactly one auth config enabled per toolkit. When a user connects the toolkit, the provider resolves the single enabled config for that toolkit and starts the OAuth flow against it.
 
-> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. With no enabled config, the connection flow fails with an error like `No ENABLED auth config for toolkit "github"` — enable one in the Composio dashboard to fix it. Enable exactly one auth config per toolkit you expose in the Builder.
+> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. With no enabled config, the connection flow fails with an error like `No ENABLED auth config for toolkit "github"`. Enable one in the Composio dashboard to fix it. Enable exactly one auth config per toolkit you expose in the Builder.
 
 ## Connect a toolkit
 
@@ -76,7 +76,7 @@ The connected account is bound to the agent, and its tools are ready to use on t
 
 ## Connection scope
 
-Each connection determines which account a tool call uses at runtime, and its _scope_ controls who shares that credential. A scope maps each call to a _bucket_ — the identity partition that a connected account is stored under. Scope is a tenancy decision made by you, the app author, not by the end user connecting an account — so you set it on the provider, not in the Builder UI.
+Each connection determines which account a tool call uses at runtime, and its _scope_ controls who shares that credential. A scope maps each call to a _bucket_, the identity partition that a connected account is stored under. Scope is a tenancy decision made by you, the app author, not by the end user connecting an account, so you set it on the provider, not in the Builder UI.
 
 - `per-author` (default): the connection belongs to the agent's author. Any invoker runs the agent with the author's account. Use this for personal agents or a single shared team account.
 - `shared`: every caller uses one shared bucket, regardless of who invokes the agent. Use this for a platform-owned account that all users should share.
@@ -92,7 +92,7 @@ const composio = new ComposioToolProvider({
 })
 ```
 
-With `caller-supplied`, the host app must forward a `resourceId` on every request so each tenant lands in its own bucket. Set `mapUserToResourceId` on the server's auth config to derive the `resourceId` from the authenticated user, so every request carries it automatically:
+With `caller-supplied`, the host app must forward a `resourceId` on every request so each tenant is routed to its own bucket. Set `mapUserToResourceId` on the server's auth config to derive the `resourceId` from the authenticated user, so every request carries it automatically:
 
 ```typescript
 export const mastra = new Mastra({

package/.docs/docs/agent-builder/memory.md

@@ -23,7 +23,7 @@ new MastraEditor({
 })
 ```
 
-Observational memory lets the agent learn long-lived facts from past conversations. Storage on the `Mastra` instance is required — see the [Memory overview](https://mastra.ai/docs/memory/overview) for the prerequisites.
+Observational memory lets the agent learn long-lived facts from past conversations. Storage on the `Mastra` instance is required, see the [Memory overview](https://mastra.ai/docs/memory/overview) for the prerequisites.
 
 ## Observational memory model
 
@@ -41,7 +41,7 @@ new MastraEditor({
       agent: {
         memory: {
           observationalMemory: {
-            model: 'openai/gpt-5.5',
+            model: 'openai/gpt-5.6-sol',
           },
         },
       },

package/.docs/docs/agent-builder/overview.md

@@ -58,7 +58,7 @@ yarn add @mastra/editor @mastra/libsql
 bun add @mastra/editor @mastra/libsql
 ```
 
-The example below defines a storage adapter, registers a builder agent, and enables the editor as explained in the prerequisites:
+The example below defines a storage adapter and registers a builder agent, plus enables the editor as explained in the prerequisites:
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'

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

@@ -2,9 +2,11 @@
 
 # Channels
 
-Channels connect an AgentController to messaging platforms like Slack, Discord, and Telegram, so a controller-backed session runs inside a chat thread. Inbound platform messages route into a controller [`Session`](https://mastra.ai/docs/agent-controller/session), and the agent's streamed output renders back to the platform with native streaming, tool approval cards, and typing status.
+Channels connect an AgentController to messaging platforms like Slack, Discord, and Telegram, so a controller-backed session runs inside a chat thread. Inbound platform messages route into a controller [`Session`](https://mastra.ai/docs/agent-controller/session), and the agent's output renders back to the platform with native streaming. The response can also include tool approval cards and typing status.
 
-AgentController channels build on the same channel layer as [agent channels](https://mastra.ai/docs/capabilities/channels/overview): the same adapters, the same configuration shape, and the same rendering pipeline. The difference is what receives the message. On an agent, the message goes straight into the agent loop. On an AgentController, the message goes into a durable session that tracks the active mode, model, permission grants, and state across the whole conversation.
+AgentController channels use the same channel layer as [agent channels](https://mastra.ai/docs/capabilities/channels/overview). The adapters and configuration shape are shared. Both channel types also use the same rendering pipeline.
+
+Message routing differs by channel type. Agent channels route messages straight into the agent loop. With AgentController channels, messages enter a durable session that tracks the active mode, model, permission grants, and state across the whole conversation.
 
 ## Configure a controller
 
@@ -77,7 +79,7 @@ Point the platform's webhook, event, or interactions URL to this path. See [Webh
 
 ## One session per chat thread
 
-Each chat thread maps to one durable controller session. The first message in a Slack or Discord thread creates a Mastra thread and a controller session keyed to it; every later message in that chat thread reuses both. The session carries the active mode, model, permission grants, and state for the life of the conversation, just like a session driven from a terminal or web UI.
+Each chat thread maps to one durable controller session. The first message in a Slack or Discord thread creates a Mastra thread and a controller session keyed to it. Every later message in that chat thread reuses both. The session carries the active mode, model, permission grants, and state for the life of the conversation, as with a session driven from a terminal or web UI.
 
 By default the session key derives from the platform and the external thread ID (`channel:slack:<THREAD_ID>`). Pass `resolveResourceId` in the channels configuration to control the mapping yourself.
 
@@ -87,7 +89,7 @@ Avoid mapping multiple active chat threads to one session. A session works on on
 
 Tools that require approval render as interactive cards with Approve and Deny buttons, the same as [agent channel tool approvals](https://mastra.ai/docs/capabilities/channels/overview). The controller run pauses at the session's approval gate until a user acts on the card, then resumes and streams the continuation back to the thread.
 
-Two behaviors follow from routing approvals through the session:
+These behaviors follow from routing approvals through the session:
 
 - A new message in the thread while an approval is pending declines that approval, the same as sending a new message in a terminal session. The new message supersedes the pending ask.
 - On adapters that can't render approval buttons (`toolDisplay: 'text'`), tools run without approval prompts so runs can't stall on a card nobody can act on.
@@ -96,8 +98,8 @@ See [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/too
 
 ## Limits
 
-- Adapters can be constructed manually as shown above. The managed connect flow (`mastra.channels.slack.connect(...)`) also supports controller-owned installations — call it with an options object (`connect({ id, name })`) to connect a controller that has no registered agent. Adapters without controller support must still be constructed manually.
-- Controller sessions are in-memory objects, so channels-backed controllers need a long-lived server. Serverless deployment isn't supported for controller channels; agent channels support it as described in [Serverless deployment](https://mastra.ai/docs/capabilities/channels/overview).
+- Adapters can be constructed manually with the same configuration. The managed connect flow (`mastra.channels.slack.connect(...)`) also supports controller-owned installations: call it with an options object (`connect({ id, name })`) to connect a controller that has no registered agent. Adapters without controller support must still be constructed manually.
+- Controller sessions are in-memory objects, so channels-backed controllers need a long-lived server. Serverless deployment isn't supported for controller channels. Agent channels support it as described in [Serverless deployment](https://mastra.ai/docs/capabilities/channels/overview).
 - Pending tool approvals don't survive a server restart. An approval card acted on after a restart is ignored as stale.
 - Mode switching from chat (for example, a `/mode` slash command) isn't available yet.
 

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

@@ -2,9 +2,9 @@
 
 # Modes
 
-Modes define the different behaviors an AgentController can run. Each mode layers its own instructions and tool overrides on top of a shared backing agent, so the same agent can act as a planner in one mode and an executor in another. The AgentController keeps exactly one mode active at a time, carries the thread and state across switches, and handles the transition between them.
+Modes define the different behaviors an AgentController can run. Each mode layers its own instructions and tool overrides on top of a shared backing agent, so the same agent can act as a planner in one mode and an executor in another. The AgentController keeps exactly one mode active at a time and carries the thread and state across switches, plus handles the transition between them.
 
-Every AgentController needs at least one mode — the `modes` array is required, and the AgentController throws at construction if it's empty. A single-purpose AgentController still defines one mode; multiple modes are how you give a session more than one behavior to switch between.
+Every AgentController needs at least one mode, the `modes` array is required, and the AgentController throws at construction if it's empty. A single-purpose AgentController still defines one mode. Multiple modes are how you give a session more than one behavior to switch between.
 
 A mode supplies three things that change how the agent behaves:
 
@@ -83,7 +83,7 @@ You can't set both `tools` and `additionalTools` on the same mode.
 
 ### Restricting tool visibility
 
-`tools` and `additionalTools` control which tools are **added** to a mode's run — they don't hide the backing agent's own tools. To restrict which of those tools the model can actually see and call, set `availableTools`:
+`tools` and `additionalTools` control which tools are **added** to a mode's run, they don't hide the backing agent's own tools. To restrict which of those tools the model can actually see and call, set `availableTools`:
 
 ```typescript
 const reviewMode = {
@@ -96,11 +96,11 @@ const reviewMode = {
 
 `availableTools` is a per-mode visibility allowlist that matches each tool by its final exposed name:
 
-- **`undefined`** (default): no mode-level restriction — every tool is visible.
+- **`undefined`** (default): no mode-level restriction: every tool is visible.
 - **`[]`**: no tools are available for this mode.
 - A denied tool stays hidden even when the list includes it. Per-tool and per-category `deny` rules in your permission config always take precedence.
 
-Workspace tools use the same list as every other tool — reference them by their exposed names (`view`, `write_file`, `find_files`, etc.). Visibility is enforced at LLM-call time, so the model never sees — and can't attempt to call — a tool outside the allowlist.
+Workspace tools use the same list as every other tool, reference them by their exposed names (`view`, `write_file`, `find_files`, etc.). Visibility is enforced at LLM-call time, so the model never sees, and can't attempt to call, a tool outside the allowlist.
 
 ### Mode transitions
 
@@ -119,7 +119,7 @@ On plan approval, the AgentController automatically switches to `build` mode. On
 
 ## Switching modes
 
-The active mode lives on the Session, so call `agentController.session.mode.switch()` to change it. The switch aborts any in-progress generation, saves the current model to the outgoing mode, and emits a `mode_changed` event. It then resolves the incoming mode's model and, when one resolves, applies it and emits a `model_changed` event:
+The active mode lives on the Session, so call `agentController.session.mode.switch()` to change it. The switch aborts any in-progress generation and saves the current model to the outgoing mode, plus emits a `mode_changed` event. It then resolves the incoming mode's model and, when one resolves, applies it and emits a `model_changed` event:
 
 ```typescript
 await agentController.session.mode.switch({ modeId: 'build' })

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

@@ -4,15 +4,17 @@
 
 > **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-The AgentController is a session controller for building interactive agent applications. It handles the runtime concerns that sit between your UI and the agent loop: managing conversation threads, switching between agent modes, persisting state, gating tool execution with approvals, and coordinating subagents. You can focus on what your agent does rather than how to wire it together.
+The AgentController is a session controller for building interactive agent applications.
 
-A AgentController exposes a [`Session`](https://mastra.ai/docs/agent-controller/session) — the per-conversation runtime state that tracks the active mode, model, thread binding, permission grants, follow-up queue, and token usage. The AgentController is the shared host; the Session is the conversation running inside it. In a multi-user host, the same AgentController can back many Sessions at once.
+It handles the runtime concerns between your UI and the agent loop. These include conversation threads, mode switches, and persistent state. It also gates tool execution with approvals and coordinates subagents. You can focus on what your agent does rather than how to wire it together.
 
-[Mastra Code](https://code.mastra.ai/) is the flagship AgentController implementation: A terminal-based coding agent with multi-model support, persistent conversations, and plan-then-execute workflows.
+An AgentController exposes a [`Session`](https://mastra.ai/docs/agent-controller/session), the per-conversation runtime state that tracks the active mode, model, thread binding, permission grants, follow-up queue, and token usage. The AgentController is the shared host. The Session is the conversation running inside it. In a multi-user host, the same AgentController can back many Sessions at once.
+
+[Mastra Code](https://code.mastra.ai/) is the flagship AgentController implementation. It's a terminal-based coding agent with multi-model support, persistent conversations, and plan-then-execute workflows.
 
 ## What you can build
 
-The AgentController gives you the runtime pieces to ship interactive agent applications. Each outcome below maps to a capability you can use today:
+The AgentController gives you the runtime pieces to release interactive agent applications. Each outcome below maps to a capability you can use today:
 
 - **Resume a conversation exactly where the user left off.** Persistent [threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) reload the active mode, model, and progress across restarts, so a coding agent or assistant picks up mid-task instead of starting over.
 - **Gate destructive actions behind human approval.** [Tool approvals and permission policies](https://mastra.ai/docs/agent-controller/tool-approvals) let you require confirmation for risky operations like file writes or deployments, while trusted tools run automatically.
@@ -32,15 +34,15 @@ Use the AgentController when your application needs:
 - Subagent orchestration to delegate focused subtasks with constrained tools
 - Session continuity with persistent threads, state, and observational memory across restarts
 
-You could assemble all of this yourself on top of the [Agent class](https://mastra.ai/docs/agents/overview), which exposes the full agent loop, tools, and memory. The AgentController is an opinionated set of defaults that wires those pieces into one application style: an ongoing session where the agent acts as a collaborator rather than a one-shot endpoint. Reach for the Agent class directly when you want full control or a request-response call; reach for the AgentController when you want the collaborative-session model without building the runtime around it.
+You could assemble all of this yourself on top of the [Agent class](https://mastra.ai/docs/agents/overview), which exposes the full agent loop, tools, and memory. The AgentController provides opinionated defaults for an ongoing session where the agent acts as a collaborator rather than a one-shot endpoint. Reach for the Agent class directly when you want full control or a request-response call. Reach for the AgentController when you want the collaborative-session model without building the runtime around it.
 
 ## Key capabilities
 
-- **Session**: Per-conversation state — active thread, mode, model, grants, follow-ups, token usage, and the display snapshot — accessed through `agentController.session`. See [Session](https://mastra.ai/docs/agent-controller/session).
+- **Session**: Per-conversation state: active thread, mode, model, grants, follow-ups, token usage, and the display snapshot: accessed through `agentController.session`. See [Session](https://mastra.ai/docs/agent-controller/session).
 - **Modes**: Define distinct agent personalities (instructions, tools, model) and switch between them without losing conversation context. See [Modes](https://mastra.ai/docs/agent-controller/modes).
 - **Threads and state**: Persist conversations and structured state across sessions, users, and mode switches. See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state).
 - **Subagents**: Spawn focused child agents with constrained tools for subtasks, optionally forking the parent conversation. See [Subagents](https://mastra.ai/docs/agent-controller/subagents).
-- **Tool approvals and permissions**: Configure which tools require user confirmation, grant session-wide exceptions, and handle interactive tool suspension. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals).
+- **Tool approvals and permissions**: Configure which tools require user confirmation and grant session-wide exceptions, plus handle interactive tool suspension. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals).
 - **Model management**: Switch models per-mode at runtime, track usage, and resolve gateway-backed models through Mastra's [model router](https://mastra.ai/models).
 - **Follow-ups and steering**: Queue messages while the agent is running, or inject mid-stream instructions to redirect the agent. Built on [signals](https://mastra.ai/docs/long-running-agents/signals).
 - **Event system**: Subscribe to typed events (message updates, mode changes, tool approvals) or coalesced `AgentControllerDisplayState` snapshots to drive your UI. See [Events](https://mastra.ai/reference/agent-controller/agent-controller-class).
@@ -59,7 +61,7 @@ const agent = new Agent({
   id: 'assistant',
   name: 'assistant',
   instructions: 'Help the user plan and complete tasks.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 const agentController = new AgentController({
@@ -119,7 +121,9 @@ The AgentController sits between your application layer and the underlying agent
 └───────────────────────────────────────┘
 ```
 
-Your app sends commands — send a message, switch mode, approve a tool call — and receives typed events such as `message_update` and `tool_approval_required`. The AgentController manages the lifecycle internally: persisting threads, routing to the correct mode agent, enforcing permissions, and emitting events as state changes.
+Your app sends commands, send a message, switch mode, approve a tool call, and receives typed events such as `message_update` and `tool_approval_required`.
+
+The AgentController manages the lifecycle internally. It persists threads and routes requests to the correct mode agent. It also enforces permissions and emits events as state changes.
 
 ## Next steps
 

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

@@ -2,13 +2,21 @@
 
 # Session
 
-A [`Session`](https://mastra.ai/reference/agent-controller/session) holds the live state of an AgentController: who the session is for, which thread is active, the selected mode and model, permission grants, queued follow-ups, token usage, application state, and the display snapshot. You reach it through `agentController.session`.
+A [`Session`](https://mastra.ai/reference/agent-controller/session) holds the live state of an AgentController. It identifies the user and active thread, along with the selected mode and model. It also stores permission grants, queued follow-ups, token usage, application state, and the display snapshot.
+
+You reach it through `agentController.session`.
 
 ## What the Session tracks
 
-The Session is the live state of a single user's interaction with the AgentController. It answers "what's true right now": who the session belongs to, which thread is currently bound, which mode and model are selected, what the user has approved, what's queued or running, the application state, and the snapshot to render. A session has one active thread at a time but can list, switch between, and clone many threads over its lifetime. Anything that describes the current state lives here; the AgentController owns the shared infrastructure every session runs on.
+The Session is the live state of a single user's interaction with the AgentController.
+
+It answers who owns the session and which thread is bound. It also identifies the selected mode and model while tracking approvals, queued or running work, application state, and the snapshot to render.
+
+A session has one active thread at a time but can list, switch between, and clone many threads over its lifetime. Anything that describes the current state lives here. The AgentController owns the shared infrastructure every session runs on.
 
-Because each session has its own identity and state, one AgentController can serve many users at once — each with a different `resourceId` backed by its own Session — without one session's mode, grants, or active thread leaking into another. Calling `createSession` with the same `resourceId` returns the existing session (get-or-create), so a resource always resumes its own session.
+Each session has its own identity and state. One AgentController can therefore serve many users at once, with a separate `resourceId` and Session preventing mode, grant, or active-thread data from leaking between users.
+
+Calling `createSession` with the same `resourceId` returns the existing session (get-or-create), so a resource always resumes its own session.
 
 The rest of this page walks through the Session's state. Each part is a focused sub-object on `agentController.session`:
 
@@ -17,7 +25,7 @@ The rest of this page walks through the Session's state. Each part is a focused
 - **What's happening right now**: [Run state](#run-state) reflects the in-flight generation, and [Follow-ups](#follow-ups) holds messages queued to send when it finishes.
 - **What you store and render**: [State](#state) holds your application's structured data, and [Display state](#display-state) is the single snapshot your UI renders from.
 
-The AgentController performs actions that change this state — switching threads, modes, or models — because those operations coordinate shared infrastructure and emit events. The Session is where you read the result. The sections below note this split where it matters.
+The AgentController performs actions that change this state, switching threads, modes, or models, because those operations coordinate shared infrastructure and emit events. The Session is where you read the result. The sections below note this split where it matters.
 
 ## Identity
 
@@ -30,7 +38,7 @@ const resourceId = agentController.session.identity.getResourceId()
 const threadId = agentController.session.thread.getId()
 ```
 
-The session `id` and `ownerId` are stable for the life of the session — they don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage, so storage layers can key sessions by a stable identifier rather than the mutable resource ID.
+The session `id` and `ownerId` are stable for the life of the session, they don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage, so storage layers can key sessions by a stable identifier rather than the mutable resource ID.
 
 The resource ID is set when creating a session via [`agentController.createSession()`](https://mastra.ai/reference/agent-controller/agent-controller-class) and defaults to the agentController `id`. See [Resource IDs](https://mastra.ai/docs/agent-controller/threads-and-state) for how it scopes threads.
 
@@ -67,7 +75,7 @@ See [Modes](https://mastra.ai/docs/agent-controller/modes) for how modes carry t
 
 ## Permission grants
 
-The AgentController owns permission _policy_ — which categories or tools require approval. The Session owns the _grants_ a user makes during the conversation. A grant lets a tool run for the rest of the session without prompting again:
+The AgentController owns permission _policy_, which categories or tools require approval. The Session owns the _grants_ a user makes during the conversation. A grant lets a tool run for the rest of the session without prompting again:
 
 ```typescript
 // Grant a category or tool for the rest of the session
@@ -105,7 +113,9 @@ Queue a follow-up with `agentController.followUp({ content })`. To redirect the
 
 ## State
 
-`session.state` holds the conversation's application state — structured values that agents and the UI share, such as model preferences, feature flags, or progress. The AgentController defines the shape with a `stateSchema`; the Session owns the live snapshot, validates updates against the schema, and emits `state_changed` on every write:
+`session.state` holds the conversation's application state, structured values that agents and the UI share, such as model preferences, feature flags, or progress.
+
+The AgentController defines the shape with a `stateSchema`. The Session owns the live snapshot and validates updates against that schema. Every write emits `state_changed`:
 
 ```typescript
 const state = agentController.session.state.get()
@@ -116,9 +126,17 @@ See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-stat
 
 ## Display state
 
-A conversation emits many fine-grained events: tokens streaming in, tools starting and finishing, approvals pending, tasks updating, token usage climbing. Subscribing to each event type and reassembling the current picture yourself is tedious and error-prone. `session.displayState` does that work for you.
+A conversation emits fine-grained events for streamed tokens and tool activity. Other events cover pending approvals, task updates, and token usage.
+
+Subscribing to each event type and reassembling the current picture yourself is tedious and error-prone.
+
+`session.displayState` does that work for you.
+
+It's a reducer-maintained snapshot.
+
+The Session keeps one `AgentControllerDisplayState` object and folds every agentController event into it as it happens, so the snapshot always reflects the latest state.
 
-It's a reducer-maintained snapshot. The Session keeps one `AgentControllerDisplayState` object and folds every agentController event into it as it happens, so the snapshot always reflects the latest state. It captures everything a UI needs to render: whether the agent is running and what it's streaming, which tools and subagents are active, anything waiting on the user such as approvals, the current task list, and running totals like token usage and queued follow-ups.
+It captures everything a UI needs to render. The snapshot shows whether the agent is running, what it's streaming, and which tools or subagents are active. It also includes pending approvals, the current task list, token usage, and queued follow-ups.
 
 Because it's a single object, you can drive an entire UI from one place: read the current snapshot with `get()`, and re-render whenever the AgentController emits `display_state_changed` (fired after every other event):
 

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

@@ -16,7 +16,7 @@ const agent = new Agent({
   id: 'assistant',
   name: 'assistant',
   instructions: 'Use subagents when a focused task needs a narrower toolset.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 const agentController = new AgentController({
@@ -47,17 +47,17 @@ const agentController = new AgentController({
 
 The parent agent can then call the auto-generated `subagent` tool with a `task` description and optional `agentType`.
 
-When you define a subagent, write its `description` and `instructions` to be clear and narrow. The `description` is what the parent model reads to decide _when_ to delegate, so state the single job the subagent is for and, by implication, what it's not for — "Reads files and gathers context without making changes" tells the parent to reach for it during exploration and to handle edits elsewhere. The `instructions` then keep the child agent inside that job. A subagent scoped to one task with a focused toolset stays predictable and is easier for the parent to route to; a broadly described subagent invites the parent to over-delegate and blurs the boundary between types. Pair the narrow scope with `allowedWorkspaceTools` so the subagent can only do what its description promises.
+When you define a subagent, give its `description` and `instructions` a clear, narrow scope. The `description` is what the parent model reads to decide _when_ to delegate, so state the single job the subagent is for and, by implication, what it's not for, "Reads files and gathers context without making changes" tells the parent to reach for it during exploration and to handle edits elsewhere. The `instructions` then keep the child agent inside that job. A subagent scoped to one task with a focused toolset stays predictable and is easier for the parent to route to. A broadly described subagent invites the parent to over-delegate and blurs the boundary between types. Pair the narrow scope with `allowedWorkspaceTools` so the subagent can only do what its description promises.
 
 For the full list of subagent configuration options, see [`AgentController` reference](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 ## Forked subagents
 
-A default subagent starts with a fresh context: it can't see the parent conversation, so you pass everything it needs in the `task` description. That's the right model for self-contained work, but it has two costs. The subagent has no access to what's already happened, and it builds a brand-new request prefix — a different system prompt and tool schemas — so it can't reuse the parent's prompt cache.
+A default subagent starts with a fresh context: it can't see the parent conversation, so you pass everything it needs in the `task` description. That's the right model for self-contained work, but it has two costs. The subagent has no access to what's already happened, and it builds a brand-new request prefix, a different system prompt and tool schemas, so it can't reuse the parent's prompt cache.
 
 **Forked subagents** solve both. Instead of a fresh agent, a fork clones the parent thread and runs the parent agent itself, so it sees the full conversation history and keeps the same system prompt and tool schemas as the parent. The identical prefix means the model's prompt cache still hits, which makes context-heavy delegation cheaper and faster.
 
-Use a fork when the subtask depends on the conversation so far — prior messages, earlier tool results, or the parent's tool environment — and you want to run it without paying to rebuild that context. Use a default subagent when the task is self-contained and benefits from a narrower toolset, a tighter system prompt, or a cheaper model.
+Use a fork when the subtask depends on the conversation so far, prior messages, earlier tool results, or the parent's tool environment, and you want to run it without paying to rebuild that context. Use a default subagent when the task is self-contained and benefits from a narrower toolset or a tighter system prompt, or alternatively a cheaper model.
 
 Enable forked mode per-type:
 
@@ -76,9 +76,12 @@ Or per-invocation via the `subagent` tool's `forked` input parameter, which over
 
 Because a fork reuses the parent agent to keep the prompt prefix stable, the subagent's own definition is mostly set aside:
 
-- Memory must be configured on the AgentController, since forking clones the parent thread. Without it, the fork call returns an error.
+- Memory must be configured on the AgentController, since forking clones the parent thread.
+
+Without it, the fork call returns an error.
+
 - The fork runs with the parent agent's instructions, tools, and model. The subagent definition's own `instructions`, `tools`, and `defaultModelId` are ignored, and a per-invocation `modelId` is ignored too.
-- Only the subagent definition's `description` still matters — it's what the parent model reads to decide when to delegate.
+- Only the subagent definition's `description` still matters: it's what the parent model reads to decide when to delegate.
 - Fork threads are tagged with `metadata.forkedSubagent === true` and hidden from `session.thread.list()` by default.
 - Recursive forks are blocked at runtime: the inherited `subagent` tool is disabled inside a fork to prevent infinite nesting.
 

package/.docs/docs/agent-controller/threads-and-state.md

@@ -2,15 +2,17 @@
 
 # Threads and state
 
-Threads and state are how an AgentController conversation survives beyond a single exchange. A **thread** is the persistent record of a conversation — its messages and metadata, saved to storage so a user can close the app and resume the same conversation later, or switch between several conversations. **State** is structured data attached to the conversation — values like model preferences, feature flags, or progress — that agents and your UI read and write as the conversation runs.
+Threads and state are how an AgentController conversation survives beyond a single exchange. A **thread** is the persistent record of a conversation, its messages and metadata, saved to storage so a user can close the app and resume the same conversation later, or switch between several conversations. **State** is structured data attached to the conversation, values like model preferences, feature flags, or progress, that agents and your UI read and write as the conversation runs.
 
-The two work together: the thread is the message history, and state is the shared scratchpad alongside it. Both persist across mode switches, model changes, and restarts, so nothing is lost when a user switches from plan mode to build mode or reopens the app the next day.
+The thread and state work together: the thread is the message history, and state is the shared scratchpad alongside it.
 
-Thread _lifecycle_ transitions — create, switch, clone, delete — live on the AgentController because they coordinate the shared thread lock and emit events. The active thread binding and thread/message _reads_ live on the [`Session`](https://mastra.ai/docs/agent-controller/session) as `agentController.session.thread`.
+Both persist across mode switches, model changes, and restarts, so nothing is lost when a user switches from plan mode to build mode or reopens the app the next day.
+
+Thread _lifecycle_ transitions, create, switch, clone, delete, live on the AgentController because they coordinate the shared thread lock and emit events. The active thread binding and thread/message _reads_ live on the [`Session`](https://mastra.ai/docs/agent-controller/session) as `agentController.session.thread`.
 
 ## Threads
 
-A thread holds one conversation's full message history. The AgentController binds the Session to one active thread at a time; messages you send and the agent's replies are appended to that thread and saved to storage. Threads let users resume a past conversation, keep several conversations side by side, or branch one into alternatives.
+A thread holds one conversation's full message history. The AgentController binds the Session to one active thread at a time. Messages you send and the agent's replies are appended to that thread and saved to storage. Threads let users resume a past conversation or keep several conversations side by side, or alternatively branch one into alternatives.
 
 ### Creating and selecting threads
 
@@ -29,7 +31,9 @@ const thread = await agentController.createThread({ title: 'New conversation' })
 
 ### Switching threads
 
-Switch to an existing thread. The agentController aborts any in-progress generation, acquires a lock on the new thread, and emits a `thread_changed` event:
+Switch to an existing thread.
+
+The agentController aborts any in-progress generation and acquires a lock on the new thread, plus emits a `thread_changed` event:
 
 ```typescript
 await agentController.switchThread({ threadId: 'thread-abc123' })
@@ -74,7 +78,7 @@ const agentController = new AgentController({
 
 ## State
 
-Where a thread stores the conversation's messages, state stores structured values that describe the conversation but aren't messages — model preferences, feature flags, UI settings, or progress markers. Agents can read and update state during a run, and your UI can react to changes, so state is how the agent and the interface stay in sync on shared facts. You define its shape with a schema, and every update is validated against that schema before it's applied.
+Where a thread stores the conversation's messages, state stores structured values that describe the conversation but aren't messages, model preferences, feature flags, UI settings, or progress markers. Agents can read and update state during a run, and your UI can react to changes, so state is how the agent and the interface stay in sync on shared facts. You define its shape with a schema, and every update is validated against that schema before it's applied.
 
 ### Defining a state schema
 
@@ -89,7 +93,7 @@ const agent = new Agent({
   id: 'assistant',
   name: 'assistant',
   instructions: 'Help the user manage a stateful session.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 const agentController = new AgentController({
@@ -134,7 +138,7 @@ The resource ID is part of a conversation's identity, so you read it from the Se
 const resourceId = agentController.session.identity.getResourceId()
 ```
 
-The session also has a stable `id` and `ownerId` (read with `session.identity.getId()` and `session.identity.getOwnerId()`). Unlike the resource ID, these don't change when you switch resources — see [Session identity](https://mastra.ai/docs/agent-controller/session) for details.
+The session also has a stable `id` and `ownerId` (read with `session.identity.getId()` and `session.identity.getOwnerId()`). Unlike the resource ID, these don't change when you switch resources, see [Session identity](https://mastra.ai/docs/agent-controller/session) for details.
 
 ## Related
 

package/.docs/docs/agent-controller/tool-approvals.md

@@ -2,11 +2,15 @@
 
 # Tool approvals and permissions
 
-The AgentController provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.
+The AgentController provides a permission system that controls which tools require user approval before execution.
+
+You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools.
+
+This gives agents with access to destructive or sensitive tools, file writes, command execution, API calls, a human-in-the-loop checkpoint before those tools run.
 
 ## Permission policies
 
-Three policies control tool behavior:
+Policies control tool behavior:
 
 - `allow`: The tool runs without prompting
 - `ask`: The tool pauses and emits a `tool_approval_required` event; the user must approve or decline
@@ -62,7 +66,7 @@ agentController.session.respondToToolApproval({ decision: 'always_allow_category
 
 ## Session grants
 
-The AgentController owns permission _policy_ (which categories require approval); the [`Session`](https://mastra.ai/docs/agent-controller/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
+The AgentController owns permission _policy_ (which categories require approval). The [`Session`](https://mastra.ai/docs/agent-controller/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
 
 ```typescript
 // Grant all edit tools for this session

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

@@ -53,7 +53,9 @@ An agent card includes fields like the agent name, description, endpoint URL, pr
 }
 ```
 
-A2A represents work as messages and tasks. Messages carry text, file, or structured data parts. Tasks are stateful units of work with IDs and lifecycle states, so clients can follow long-running work, send follow-up turns, cancel work, or resubscribe after a disconnect.
+A2A represents work as messages and tasks. Messages carry text, file, or structured data parts.
+
+Tasks are stateful units of work with IDs and lifecycle states. Clients can follow long-running work and send follow-up turns. They can also cancel work or resubscribe after a disconnect.
 
 ## Get started
 
@@ -83,7 +85,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Answer user questions and delegate weather questions when needed.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: {
     remoteWeatherAgent,
   },