@mastra/mcp-docs-server 1.1.46 → 1.1.48

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

@@ -15,18 +15,18 @@ The Agent Builder ships with two supported roles: `admin` and `member`. Wire the
 
 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, runs, and stream Builder workflows      |
-| `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                    |
-| `stored-workspaces:*`                 | Pick a workspace when editing an agent                        |
-| `tools:read`, `tools:execute`         | Populate the tool picker and run tools through agents         |
-| `workflows:read`, `workflows:execute` | Populate the workflow picker and run workflows through agents |
-| `memory:read`                         | Preview memory configuration in the picker                    |
-| `channels:read`                       | Show Slack/channel chips on agent pages                       |
-| `infrastructure:read`                 | Builder diagnostics banner on the shell                       |
+| 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. |
+| `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                                                                                                                  |
+| `stored-workspaces:*`                 | Pick a workspace when editing an agent                                                                                                                      |
+| `tools:read`, `tools:execute`         | Populate the tool picker and run tools through agents                                                                                                       |
+| `workflows:read`, `workflows:execute` | Populate the workflow picker and run workflows through agents                                                                                               |
+| `memory:read`                         | Preview memory configuration in the picker                                                                                                                  |
+| `channels:read`                       | Show Slack/channel chips on agent pages                                                                                                                     |
+| `infrastructure:read`                 | Builder diagnostics banner on the shell                                                                                                                     |
 
 Grant `:write`, `:delete`, and `:publish` on `stored-agents` and `stored-skills` for users who should create or modify agents. The `:*` wildcards in the table above cover those actions. `admin` covers everything through the `*` wildcard.
 
@@ -85,13 +85,13 @@ export const mastra = new Mastra({
 
 Permission patterns follow `resource:action`. Wildcards are supported on either side:
 
-- `*` — full access (every resource, every action). Used by `admin`.
-- `agent-builder:*` — every action on the `agent-builder` resource.
-- `*:read` — `read` across every resource.
+- `*`: Full access (every resource, every action). Used by `admin`.
+- `agent-builder:*`: Every action on the `agent-builder` resource.
+- `*:read`: `read` Across every resource.
 
 Patterns resolve through `matchesPermission()`. The first matching role permission grants the action.
 
 ## Related
 
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire RBAC alongside the rest of the Builder config.
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying) — auth, RBAC, and EE license setup for production.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire RBAC alongside the rest of the Builder config.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Auth, RBAC, and EE license setup for production.

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

@@ -2,7 +2,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 can give end-user agents a browser tool driven by a registered provider. Unlike filesystems and sandboxes, **there are no built-in browser providers** — you must register one through `MastraEditor.browsers`.
+The Agent Builder can give end-user agents a browser tool driven by a registered provider. Unlike filesystems and sandboxes, **there are no built-in browser providers** and you must register one through `MastraEditor.browsers`.
 
 ## Quickstart
 
@@ -44,9 +44,9 @@ new MastraEditor({
 
 `MastraEditor.browsers` accepts a `Record<string, BrowserProvider>`. Each provider exposes:
 
-- `id` — provider identifier, matched against `StorageBrowserConfig.provider` (e.g., `'stagehand'`).
-- `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.
+- `id`: Provider identifier, matched against `StorageBrowserConfig.provider` (e.g., `'stagehand'`).
+- `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.
 
@@ -56,6 +56,6 @@ The `features.agent.browser` toggle controls whether end users can enable browse
 
 ## Related
 
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `browser` field schema.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the full Builder config surface, including `features.agent.browser`.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `browser` alongside the rest of the Builder config.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `browser` field schema.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): The full Builder config surface, including `features.agent.browser`.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `browser` alongside the rest of the Builder config.

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

@@ -63,8 +63,8 @@ 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.
+- `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.
 
 ## Storage requirement
 
@@ -72,5 +72,5 @@ The Slack provider handles app creation, OAuth, slash commands, and message rout
 
 ## Related
 
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying) — set a public `baseUrl` for production deployments.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire channel toggles into the Builder UI.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Set a public `baseUrl` for production deployments.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire channel toggles into the Builder UI.

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

@@ -39,43 +39,26 @@ new MastraEditor({
         tools: true,
         agents: true,
         workflows: true,
+        scorers: true,
         skills: true,
         memory: true,
+        variables: true,
+        favorites: true,
+        avatarUpload: true,
         model: true,
         browser: true,
-        avatarUpload: true,
-        favorites: true,
       },
     },
   },
 })
 ```
 
-The shipping UI consumes these `AgentFeatures` keys: `tools`, `agents`, `workflows`, `skills`, `memory`, `model`, `browser`, `avatarUpload`, and `favorites`. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full schema.
+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.
 
 ## Admin defaults
 
 `builder.configuration.agent` pins admin-controlled defaults onto every agent the Builder produces.
 
-```typescript
-new MastraEditor({
-  builder: {
-    enabled: true,
-    configuration: {
-      agent: {
-        models: {
-          allowed: [
-            { provider: 'openai', modelId: 'gpt-5.4-mini' },
-            { provider: 'openai', modelId: 'gpt-5.4' },
-            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
-          ],
-        },
-      },
-    },
-  },
-})
-```
-
 `configuration.agent` accepts `models`, `memory`, `workspace`, `browser`, `tools`, `agents`, and `workflows`. See the [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) for the full shape.
 
 ## Making tools, agents, and workflows available
@@ -118,9 +101,9 @@ MCP tools work the same way: load them via `MCPClient.getTools()` and spread the
 
 `configuration.agent.tools`, `configuration.agent.agents`, and `configuration.agent.workflows` constrain which registered entries appear in the Builder's pickers. Allowlist semantics are the same for all three:
 
-- **Omitted**: unrestricted. The picker shows every registered entry.
-- **`allowed: []`**: explicit lockdown. The picker is empty.
-- **`allowed: [...ids]`**: the picker shows only the listed IDs.
+- **Omitted**: Unrestricted. The picker shows every registered entry.
+- **`allowed: []`**: Explicit lockdown. The picker is empty.
+- **`allowed: [...ids]`**: The picker shows only the listed IDs.
 
 Unknown IDs are dropped and surfaced as warnings through `getModelPolicyWarnings()` and the server logs.
 
@@ -141,7 +124,7 @@ new MastraEditor({
 
 ## Related
 
-- [Model policy](https://mastra.ai/docs/agent-builder/model-policy) — pin the allowed models and default model.
-- [Memory](https://mastra.ai/docs/agent-builder/memory) — set the default memory shape for new agents.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — full property list.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — every field on `configuration.agent`.
+- [Model policy](https://mastra.ai/docs/agent-builder/model-policy): Pin the allowed models and default model.
+- [Memory](https://mastra.ai/docs/agent-builder/memory): Set the default memory shape for new agents.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): Full property list.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Every field on `configuration.agent`.

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

@@ -2,16 +2,16 @@
 
 > **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.
 
-Production deployments swap the local primitives in the Quickstart for cloud-backed equivalents. The shape of the `Mastra` and `MastraEditor` config doesn't change — only the providers behind it.
+Production deployments swap the local primitives in the Quickstart for cloud-backed equivalents. The shape of the `Mastra` and `MastraEditor` config doesn't change, only the providers behind it.
 
 ## What a production deployment needs
 
-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.
-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.
+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.
+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.
 
 ## EE license
 
@@ -101,7 +101,7 @@ new Mastra({
 
 `S3Filesystem` uses the default AWS credential chain (environment variables, `~/.aws` config, IAM roles, EC2 instance profile). For long-running deployments, use a credential provider function so credentials refresh automatically.
 
-`DockerSandbox` and `VercelSandbox` are alternative cloud sandbox providers — pick whichever matches your runtime.
+`DockerSandbox` and `VercelSandbox` are alternative cloud sandbox providers, pick whichever matches your runtime.
 
 > **Warning:** A local sandbox can't run commands safely in a shared environment. Always register a cloud sandbox provider and reference it in the workspace config before deploying.
 
@@ -117,5 +117,5 @@ Slack needs to reach your server through a public URL. Pass `baseUrl` to `SlackP
 
 ## Related
 
-- [Access control](https://mastra.ai/docs/agent-builder/access-control) — auth and RBAC setup.
-- [Channels](https://mastra.ai/docs/agent-builder/channels) — Slack `baseUrl` and channel-specific setup.
+- [Access control](https://mastra.ai/docs/agent-builder/access-control): Auth and RBAC setup.
+- [Channels](https://mastra.ai/docs/agent-builder/channels): Slack `baseUrl` and channel-specific setup.

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

@@ -60,6 +60,6 @@ If a required adapter is missing, Mastra throws a descriptive error at agent run
 
 ## Related
 
-- [Memory overview](https://mastra.ai/docs/memory/overview) — concepts and core configuration.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `memory` field schema.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `memory` alongside the rest of the Builder config.
+- [Memory overview](https://mastra.ai/docs/memory/overview): Concepts and core configuration.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `memory` field schema.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `memory` alongside the rest of the Builder config.

package/.docs/docs/agent-builder/model-policy.md

@@ -43,6 +43,6 @@ See the [`builder.configuration.agent.models`](https://mastra.ai/reference/edito
 
 ## Related
 
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire the model policy into the broader Builder config.
-- [`builder.configuration.agent.models`](https://mastra.ai/reference/editor/agent-builder/builder-models) — full property list.
-- [Provider registry](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/llm/model/provider-registry.json) — every model ID Mastra recognizes out of the box.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire the model policy into the broader Builder config.
+- [`builder.configuration.agent.models`](https://mastra.ai/reference/editor/agent-builder/builder-models): Full property list.
+- [Provider registry](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/llm/model/provider-registry.json): Every model ID Mastra recognizes out of the box.

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

@@ -7,6 +7,8 @@ The Agent Builder lets you build, configure, and operate Mastra agents all withi
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
 - [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
 - [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
+- [**Workspace**](https://mastra.ai/docs/agent-builder/workspace): Configure the default filesystem, sandbox, and skills workspace for Builder-created agents.
+- [**Browser**](https://mastra.ai/docs/agent-builder/browser): Register browser providers and pin a default browser configuration.
 - [**Access control**](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder behind Mastra RBAC roles and permissions.
 - [**Channels**](https://mastra.ai/docs/agent-builder/channels): Connect Builder-created agents to Slack and other channels.
 - [**Tool providers**](https://mastra.ai/docs/agent-builder/integrations): Connect Builder-created agents to third-party apps through OAuth-backed tool providers.
@@ -15,9 +17,18 @@ The Agent Builder lets you build, configure, and operate Mastra agents all withi
 
 For building agents entirely in code, see the [Agents overview](https://mastra.ai/docs/agents/overview). For editing code-defined agents through Studio, see the [Editor overview](https://mastra.ai/docs/editor/overview).
 
+## Prerequisites
+
+The Agent Builder requires:
+
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+- **Storage**: A `@mastra/core` storage adapter on the `Mastra` instance. Agents, memory, and workspace state all persist through `Mastra.storage`.
+- **A builder agent**: Register a `builderAgent` created with the `createBuilderAgent()` factory from `@mastra/editor/ee` on `Mastra.agents`. The chat-based editor invokes it through the same `Mastra.getAgent(id)` lookup as any other agent. Without this registration, the chat-based editor returns 404.
+- **Model credentials**: `createBuilderAgent()` uses an OpenAI model by default, which requires `OPENAI_API_KEY`. To use a different provider, pass a `model` override to `createBuilderAgent({ model })` and set that provider's credentials instead.
+
 ## Get started
 
-Install `@mastra/editor` alongside a storage adapter:
+Install `@mastra/editor` alongside a storage adapter. This example uses `@mastra/libsql`:
 
 **npm**:
 
@@ -43,7 +54,7 @@ yarn add @mastra/editor @mastra/libsql
 bun add @mastra/editor @mastra/libsql
 ```
 
-Wire the Agent Builder onto a `Mastra` instance:
+The example below defines a storage adapter, registers a builder agent, and enables the editor as explained in the prerequisites:
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
@@ -67,7 +78,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Start the dev server:
+Start Mastra's development server:
 
 ```bash
 npx mastra dev
@@ -75,14 +86,6 @@ npx mastra dev
 
 The Agent Builder is mounted at `http://localhost:4111/agent-builder`.
 
-## Prerequisites
-
-The Agent Builder requires:
-
-- **Storage**: An `@mastra/core` storage adapter on the `Mastra` instance. Agents, memory, and workspace state all persist through `Mastra.storage`.
-- **The Builder agent**: Register a Builder agent created with the `createBuilderAgent()` factory from `@mastra/editor/ee` on `Mastra.agents`. The chat-based editor invokes it through the same `Mastra.getAgent(id)` lookup as any other agent. Without this registration, the chat-based editor returns 404.
-- **`OPENAI_API_KEY`**: The Builder agent created by `createBuilderAgent()` runs on an OpenAI model, so an `OPENAI_API_KEY` environment variable is required.
-
 ## Disabling the Builder
 
 Set `enabled: false` to keep the config in place but turn the surface off:
@@ -95,4 +98,10 @@ new MastraEditor({
 })
 ```
 
-Omitting the `builder` field has the same effect.
+Omitting the `builder` field has the same effect.
+
+## Next steps
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Toggle Builder surfaces and pin defaults for new agents.
+- [Access control](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder with authentication and role-based access control.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.

package/.docs/docs/agent-builder/skill-registries.md

@@ -27,5 +27,5 @@ The Builder library tab now exposes a **Browse** view backed by skills.sh. End u
 
 ## Related
 
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire registries alongside the rest of the Builder config.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — every field on `builder`.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire registries alongside the rest of the Builder config.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): Every field on `builder`.

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

@@ -41,8 +41,8 @@ The Builder derives a deterministic id from the inline config and persists the s
 
 `configuration.agent.workspace` accepts a `StorageWorkspaceRef`:
 
-- **`{ type: 'inline', config }`** — embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
-- **`{ type: 'id', workspaceId }`** — references a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
+- **`{ type: 'inline', config }`**: Embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
+- **`{ type: 'id', workspaceId }`**: References a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
 
 See the [StorageWorkspaceRef reference](https://mastra.ai/reference/editor/storage-workspace-ref) for both variants.
 
@@ -54,7 +54,7 @@ For cloud deployments, swap `LocalFilesystem` / `LocalSandbox` for managed provi
 
 ## Related
 
-- [Workspace overview](https://mastra.ai/docs/workspace/overview) — the underlying workspace model.
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox) — the building blocks.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `workspace` field schema.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `workspace` alongside the rest of the Builder config.
+- [Workspace overview](https://mastra.ai/docs/workspace/overview): The underlying workspace model.
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox): The building blocks.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `workspace` field schema.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `workspace` alongside the rest of the Builder config.

package/.docs/docs/agents/goals.md

@@ -0,0 +1,110 @@
+# Goals
+
+**Added in:** `@mastra/core@1.42.0`
+
+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 is 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.
+
+> **Note:** Goals are experimental and may change in a future release.
+
+## When to use goals
+
+Use a goal when you want an agent to keep working toward a single objective across many iterations and messages, without re-supplying the success criteria on every call:
+
+- A standing objective the agent should pursue until a judge says it's done.
+- Work that should continue across mid-run messages (a message delivered into a live run is still judged against the goal).
+- An objective that must persist across thread reloads or process restarts.
+
+For a one-off completion check within a single `stream()` call, use [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents) instead.
+
+## Quickstart
+
+Goals require a configured [storage](https://mastra.ai/docs/memory/storage) 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'
+
+const worker = new Agent({
+  name: 'worker',
+  instructions: 'You complete software tasks end to end.',
+  model: 'openai/gpt-5.5',
+  memory,
+  goal: {
+    judge: 'openai/gpt-5-mini',
+    maxRuns: 50,
+  },
+})
+
+// Set the durable objective for a thread.
+await worker.setObjective('Add and test a /health endpoint', {
+  threadId,
+  resourceId,
+})
+
+// The objective is judged each iteration until it's complete or maxRuns is hit.
+const stream = await worker.stream('Start working on the goal', {
+  memory: { thread: threadId, resource: resourceId },
+})
+```
+
+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.
+
+## 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.
+- **Satisfied** → the loop stops and the objective is marked `done`.
+- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops but the objective stays `active`, so raising `maxRuns` later can resume it.
+
+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 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).
+
+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.
+
+```typescript
+const worker = new Agent({
+  name: 'worker',
+  instructions: 'You complete software tasks end to end.',
+  model: 'openai/gpt-5.5',
+  memory,
+  goal: {
+    // A resolver function lets you inject provider credentials and read the
+    // current judge selection at runtime; returning `undefined` keeps the
+    // goal step a no-op.
+    judge: ({ requestContext }) => resolveJudgeModel(requestContext),
+    maxRuns: 30,
+    prompt: 'Only mark the goal complete when tests pass.',
+  },
+})
+```
+
+Each evaluation emits a typed `goal` stream chunk (`GoalEvaluationPayload`: `objective`, `iteration`, `maxRuns`, `passed`, `status`, `results`, `reason`, `duration`, `timedOut`, `maxRunsReached`, `suppressFeedback`) so a UI can show goal progress mid-run.
+
+## Managing the objective
+
+Control the objective for a thread with `Agent` methods. All of them no-op when the run is not memory-backed (they require storage and a `threadId`):
+
+```typescript
+// Read the current objective record.
+const record = await worker.getObjective({ threadId })
+
+// Update options on the active objective (only provided fields are written;
+// unset fields fall back to the agent's `goal` config).
+await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
+
+// Drop the objective.
+await worker.clearObjective({ threadId })
+```
+
+Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state.
+
+> **Note:** See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
+
+## Related
+
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
+- [Signal providers](https://mastra.ai/docs/agents/signal-providers) — how the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/memory/storage) — the storage backend goals require

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

@@ -224,6 +224,8 @@ export const weatherTool = createTool({
 })
 ```
 
+`toModelOutput` also works on client-side tools passed through `clientTools`. The mapping runs on the client after the tool executes, and the transformed output is sent back to the server alongside the raw result.
+
 ## Transform tool payloads for UI and transcripts
 
 Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.

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

@@ -84,10 +84,26 @@ const browser = new AgentBrowser({
 
 AgentBrowser uses accessibility tree refs to identify elements. When an agent calls `browser_snapshot`, it receives a text representation of the page with refs like `@e1`, `@e2`, etc. The agent then uses these refs with other tools to interact with elements.
 
+## Recording
+
+AgentBrowser can opt into alpha browser recording tools:
+
+```typescript
+const browser = new AgentBrowser({
+  headless: false,
+  recording: {
+    outputDir: './browser-recordings',
+  },
+})
+```
+
+This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details.
+
 > **Note:** See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
 
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

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

@@ -7,6 +7,7 @@ Mastra supports two SDK providers and one CLI provider:
 - [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
 - [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
 - [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
+- [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
 ## When to use browser
 
@@ -164,5 +165,6 @@ const browser = new AgentBrowser({
 
 - [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/browser/recording.md

@@ -0,0 +1,108 @@
+# Browser recording (alpha)
+
+Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.
+
+> **Caution:** Browser recording is an alpha feature. The API and output format may change.
+
+## When to use browser recording
+
+Use browser recording when you need to:
+
+- Review what an agent did in a browser
+- Share a short browser automation run with a teammate
+- Debug missed actions, slow page loads, or unexpected navigation
+- Add short captions that explain each major step
+
+Recording tools are disabled by default. Enable them only for agents that need to write video files.
+
+## Enable recording
+
+Pass `recording.outputDir` to `AgentBrowser` or `StagehandBrowser`. The browser provider adds the `browser_record` and `browser_record_caption` tools to the agent's toolset.
+
+The following example enables recording for `AgentBrowser`:
+
+```typescript
+import { join } from 'node:path'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+export const browser = new AgentBrowser({
+  headless: false,
+  recording: {
+    outputDir: join(process.cwd(), 'browser-recordings'),
+  },
+})
+```
+
+The same option works with `StagehandBrowser`:
+
+```typescript
+import { join } from 'node:path'
+import { StagehandBrowser } from '@mastra/stagehand'
+
+export const browser = new StagehandBrowser({
+  headless: false,
+  recording: {
+    outputDir: join(process.cwd(), 'browser-recordings'),
+  },
+})
+```
+
+## Recording tools
+
+Enabling recording adds these tools:
+
+| Tool                     | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `browser_record`         | Starts, stops, or checks the status of a recording.          |
+| `browser_record_caption` | Adds a short caption at the current moment in the recording. |
+
+`browser_record` accepts an `action` field:
+
+- `start`: Start recording the current browser session.
+- `status`: Check whether a recording is active.
+- `stop`: Stop recording and write the `.avi` file.
+
+The `outputPath` option for `browser_record` must be an absolute path inside the configured `recording.outputDir`. If you omit it, Mastra creates a file in `outputDir`.
+
+## Example agent instructions
+
+Tell the agent when to record and when to add captions:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { browser } from '../browsers'
+
+export const browserAgent = new Agent({
+  id: 'browser-agent',
+  name: 'Browser Agent',
+  model: 'openai/gpt-5.5',
+  browser,
+  instructions: `Use browser tools to complete the requested task.
+
+When the user asks for a recording:
+1. Call browser_record with action="start" before browser work begins.
+2. After each major action, call browser_record_caption with a caption of about six words.
+3. Call browser_record with action="stop" as soon as the task is complete.
+4. Return the saved video path to the user.`,
+})
+```
+
+## Output format and limits
+
+Recordings are saved as Motion-JPEG AVI files. This format is encoded in JavaScript and does not require `ffmpeg` or native dependencies.
+
+Default limits:
+
+- Maximum duration: 30 seconds
+- Hard duration cap: 120 seconds
+- Maximum frame size: 1024 × 720
+- Captions: 80 characters each
+- One active recording per process
+
+Use shorter recordings when possible. Long browser sessions produce larger files and are harder to review.
+
+## Next steps
+
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Browser overview](https://mastra.ai/docs/browser/overview)

package/.docs/docs/browser/stagehand.md

@@ -146,8 +146,25 @@ const browser = new StagehandBrowser({
 
 > **Note:** See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
 
+## Recording
+
+Stagehand can opt into alpha browser recording tools:
+
+```typescript
+const browser = new StagehandBrowser({
+  headless: false,
+  model: 'openai/gpt-5.5',
+  recording: {
+    outputDir: './browser-recordings',
+  },
+})
+```
+
+This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details.
+
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
 - [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser)

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

@@ -6,7 +6,7 @@ This page explains both mechanisms and how they differ between Studio and Server
 
 ## Project config
 
-The `.mastra-project.json` file is auto-generated on your first Studio or Server deploy. It links your local project to a platform project.
+The `.mastra-project.json` file is auto-generated on your first Studio or Server deploy. It links your local project to a platform project. The [GitHub integration](https://mastra.ai/docs/mastra-platform/github) writes the same file into linked repositories.
 
 Commit it to your version control so that subsequent deploys (including from CI) target the correct project.
 

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

@@ -0,0 +1,150 @@
+# Hosted databases
+
+From your [platform](https://mastra.ai/docs/mastra-platform/overview) project settings, provision a fully managed database and attach it to your project. Mastra creates it with your provider, stores credentials securely, and injects connection details as runtime environment variables when the database is ready, so there are no connection strings to copy or configure.
+
+## When to use hosted databases
+
+Use a hosted database when your project needs durable storage that's managed by the platform, including:
+
+- **Agent memory**: Persist conversation history, working memory, and semantic recall across sessions.
+- **Application data**: Store and retrieve relational or structured data your project needs at runtime.
+- **Vector search**: Store embeddings for retrieval-augmented generation and semantic search.
+
+## Providers
+
+Hosted databases are available through three providers. Pick one when you attach a database from project settings. Mastra provisions it with the provider, stores credentials securely, and injects connection details as runtime environment variables when the database is ready. Wire those variables into the matching Mastra storage adapter in your code.
+
+You can attach one database per provider to a project. This keeps environment variable names unambiguous — for example, a project has a single `DATABASE_URL` for Postgres and separate `TURSO_*` variables for Turso. Attach Turso and Postgres to the same project when you need separate stores for different workloads.
+
+For most agent-focused projects, **Turso** is the simplest starting point. It provides a lightweight, SQLite-compatible engine well suited to agent memory, conversation history, and per-tenant isolation. Choose **Postgres** when your workload needs full SQL, relational schemas, or structured application data beyond Mastra runtime state. **MongoDB** (_coming soon_) will add document storage and built-in vector search for workloads that don't map cleanly to SQL.
+
+| Provider       | Engine                     | Best for                                        |
+| -------------- | -------------------------- | ----------------------------------------------- |
+| **Turso**      | LibSQL, SQLite-compatible  | Agent memory, per-tenant isolation              |
+| **PostgreSQL** | Serverless Postgres        | Relational workloads, structured data           |
+| **MongoDB**    | Document and vector search | Document storage, vector search (_coming soon_) |
+
+## Attach a database
+
+1. Open your project in the [platform](https://mastra.ai/docs/mastra-platform/overview) and go to **Project Settings**.
+
+2. Open the **Database** section, then select **Add database**.
+
+3. Select a **provider** (Turso or Postgres). You can switch providers before attaching.
+
+4. Configure the database:
+
+   - **Name**: A label for the database within your project.
+   - **Region**: Where the database is hosted. Select the region closest to your users. Turso defaults to `sjc` (San Jose) and is available in 20+ locations worldwide. Postgres defaults to `aws-us-west-2` and is available across AWS and Azure regions in the US, EU, and APAC.
+
+5. Select **Attach database**. Provisioning runs in the background. The database starts in a `provisioning` state and moves to `ready` once the provider finishes setup. Connection details are injected into your project as server runtime environment variables automatically.
+
+> **Note:** Hosted databases are created from your platform project settings. There is currently no CLI or public API for provisioning them.
+
+## Connect from your code
+
+When a database is `ready`, the provider has finished provisioning and the platform has injected connection details as managed environment variables. Check status in **Project Settings → Database** — each attached database shows `provisioning` while setup runs in the background, then `ready` when you can connect. Open a `ready` database to view its environment variables and a copy-pasteable code snippet. Wire those variables into a Mastra storage adapter, with no manual configuration required.
+
+### Turso (LibSQL)
+
+Turso exposes two environment variables: `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN`. The following example connects a [LibSQLStore](https://mastra.ai/reference/storage/libsql) using those variables.
+
+```ts
+import { LibSQLStore } from '@mastra/libsql'
+
+export const storage = new LibSQLStore({
+  url: process.env.TURSO_DATABASE_URL!,
+  authToken: process.env.TURSO_AUTH_TOKEN!,
+})
+```
+
+Install the adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/libsql@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/libsql@latest
+```
+
+### PostgreSQL
+
+PostgreSQL exposes a single `DATABASE_URL` connection string. The following example connects a [PostgresStore](https://mastra.ai/reference/storage/postgresql) using that variable.
+
+```ts
+import { PostgresStore } from '@mastra/pg'
+
+export const storage = new PostgresStore({
+  connectionString: process.env.DATABASE_URL!,
+})
+```
+
+Install the adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/pg@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/pg@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/pg@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/pg@latest
+```
+
+Pass the `storage` instance to your `Mastra` configuration so agents, memory, and workflows can use it:
+
+```ts
+import { Mastra } from '@mastra/core'
+import { storage } from './storage'
+
+export const mastra = new Mastra({
+  storage,
+})
+```
+
+## Environment variables
+
+Each provider injects a fixed set of managed environment variables. These are available to your project at runtime when the database is `ready`. You don't define them yourself.
+
+| Provider | Variables                                |
+| -------- | ---------------------------------------- |
+| Turso    | `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN` |
+| Postgres | `DATABASE_URL`                           |
+
+> **Warning:** Treat connection credentials as secrets. The auth token (`TURSO_AUTH_TOKEN`) and the Postgres connection string (`DATABASE_URL`) grant full access to your data. The platform masks them by default and only reveals them on request.
+
+## Manage a database
+
+- **View connection details**: Open a `ready` database in your project settings to see its environment variables and a copy-pasteable code snippet.
+- **Detach**: Removing a database from a project deletes it with the provider and clears its injected environment variables. This is irreversible, so ensure you no longer need the data.

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

@@ -0,0 +1,131 @@
+# GitHub integration on Mastra platform
+
+The GitHub integration links a Mastra platform project to a GitHub repository. When you push changes to your repository Studio and Server will automatically be deployed.
+
+> **Note:** The integration only works with repositories hosted on GitHub.com. Self-hosted GitHub Enterprise instances are not currently supported.
+
+After a repository is linked, the platform:
+
+- Builds and deploys Studio and Server on every push to the configured branches.
+- Provisions managed databases and the Mastra gateway API key for projects created from a template.
+- Surfaces commit, branch, and pull request context on each deploy.
+- Reports build status back to GitHub as check runs and to the project dashboard with live status badges and inline logs.
+
+## When to use the GitHub integration
+
+Choose the GitHub integration when you want one of the following:
+
+- Push-to-deploy from `main` or any other branch, including separate branches for Studio and Server.
+- A managed onboarding flow that scaffolds a project from a Mastra template, including a fresh repository, managed database, and gateway API key.
+- Pull-request and commit context inside the platform dashboard for triage.
+
+The CLI flow (`mastra studio deploy` and `mastra server deploy`) is still available for ad-hoc deploys and CI providers other than GitHub. See [Studio](https://mastra.ai/docs/mastra-platform/studio) and [Server](https://mastra.ai/docs/mastra-platform/server) for the CLI-only path.
+
+## Install the Mastra GitHub App
+
+The integration is powered by the Mastra GitHub App. The App reads repository contents, listens for `push` events on the configured branches, and writes deploy status back as check runs.
+
+1. In the [Mastra platform dashboard](https://projects.mastra.ai), open your organization settings. The page includes a **GitHub App** section.
+
+2. Select **Install GitHub App** and choose the GitHub account or organization to install on.
+
+   If you don't own the GitHub organization, GitHub creates a pending **installation request** that an admin must approve. The dashboard tracks pending requests alongside completed installations.
+
+3. Select the repositories the App can access. You can scope to specific repositories or grant access to all repositories on the account.
+
+   You can revoke or change repository access at any time from GitHub's App settings.
+
+> **Note:** If GitHub later updates the App's required permissions, the dashboard surfaces an **outdated permissions** warning with an approval link. Repository operations return a `403` until an admin re-approves.
+
+### Pending installation requests
+
+When a non-admin requests the App on an organization, the request stays pending until an organization admin approves it on GitHub.com. The dashboard:
+
+- Lists pending requests next to active installations.
+- Lets the same user request access to multiple GitHub accounts at once.
+- Reconciles pending state against GitHub when you open the page, removing requests an admin has declined or the requester has withdrawn.
+
+To cancel a pending request, select **Cancel** next to it in the dashboard.
+
+## Create a project from a template
+
+Templates are the fastest way to get started. The platform creates a new repository from a Mastra template, links it to a fresh project, provisions any managed databases the template declares, and runs the first deploy.
+
+1. In the dashboard, select **Create project** and choose **Start from a template**.
+
+2. Pick a template and select the GitHub account that owns the new repository. Name the repository and choose whether it should be private.
+
+3. Configure the template's managed database requirements. Templates can declare required databases (such as Turso or Neon) and you pick the provider and region per requirement.
+
+4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Mastra gateway works on the first deploy.
+
+5. Select **Create project**. The platform creates the repository, writes a `.mastra-project.json` config file into it, provisions the managed databases, and triggers the initial Studio and Server deploys.
+
+The initial deploy waits for managed databases to finish provisioning before it starts, so the template's first build sees the database connection environment variables.
+
+## Link an existing repository
+
+Use this flow when you already have a Mastra project in a GitHub repository.
+
+1. In the dashboard, select **Create project** and choose **Connect an existing repository**, or open an existing project and select **Link repository** from the project settings.
+
+2. Pick an installation, then choose the repository. Repository search works across every repository the App has access to on that installation.
+
+3. Choose the Studio and Server deploy branches. Both targets default to the repository's default branch, and they can share a branch or use different branches.
+
+   You can disable Studio or Server for the project. The manual **Deploy from GitHub** drawer selects both targets by default when both are configured.
+
+4. Select **Link repository**. The platform validates that the repository doesn't already have a `.mastra-project.json` file pointing at a different project. If it does, the dashboard warns you and offers an **Overwrite** option that replaces the file on link.
+
+After linking, the next push to the configured branch triggers a deploy.
+
+### `.mastra-project.json` conflicts
+
+The platform writes a `.mastra-project.json` file into every linked repository to identify the project. When you link a repository that already has one of these files, the dashboard checks its contents before submitting:
+
+- **Missing**: The platform creates the file on link.
+- **Matching**: The file already points at the project you're linking, so no change is needed.
+- **Conflicting**: The file points at a different project. You can cancel or explicitly overwrite the file.
+
+See [Configuration](https://mastra.ai/docs/mastra-platform/configuration) for the file's schema.
+
+## Push-to-deploy
+
+After a repository is linked, every push to a configured branch triggers a deploy:
+
+- A push to the **Studio branch** triggers a Studio deploy.
+- A push to the **Server branch** triggers a Server deploy.
+- If both targets share a branch, one push triggers both deploys in parallel.
+
+Each deploy carries the commit SHA, branch, and (when available) the pull request number that introduced the commit. Builds run inside the platform and report status back to GitHub as check runs on the commit.
+
+Only one build per deploy target runs at a time. If a new push arrives while a build is in progress, the platform cancels older queued builds for that same target and runs the latest. Studio and Server builds are tracked independently, so they can run in parallel when both targets are configured.
+
+### Manual GitHub deploys
+
+You can also trigger a deploy from the dashboard without pushing. Open the project, select **Deploy from GitHub**, pick the target (Studio, Server, or both) and a branch, and submit. The platform runs the deploy against the head commit of that branch and records the trigger as a **GitHub Workflow** deploy.
+
+## Track deploys
+
+After a project is created from a template or linked to a repository, the **Setup** page shows one row per deploy target. Each row:
+
+- Displays a live status badge that polls the deploy until it finishes.
+- Links to the deploy detail page via the deploy ID.
+- Exposes a **Show logs** toggle that streams build and runtime logs inline. Server logs poll every three seconds while the deploy is active.
+
+## Permissions and revocation
+
+To stop deploys from a repository, do one of the following:
+
+- **Unlink the repository** from the project in **Project settings → Repository**. The project keeps its history and you can re-link a different repository later.
+- **Remove repository access** for the Mastra GitHub App on GitHub.com. Existing deploys keep running, but no new push triggers a deploy.
+- **Uninstall the GitHub App** from the GitHub account. This removes access to every repository on that account.
+
+If GitHub revokes or rotates the App's installation token, repository reads return a `github_app_permissions_outdated` error and the dashboard prompts an admin to re-approve permissions.
+
+## Related
+
+- [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview)
+- [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio)
+- [Server on Mastra platform](https://mastra.ai/docs/mastra-platform/server)
+- [Configuration](https://mastra.ai/docs/mastra-platform/configuration)

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

@@ -6,6 +6,10 @@ The [Mastra platform](https://projects.mastra.ai) provides three products for de
 - [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces. Starting with Studio also gives you Observability.
 - [**Server**](https://mastra.ai/docs/mastra-platform/server): A production deployment target that runs your Mastra application as an API server. Starting with Server also gives you Observability.
 
+You can deploy Studio and Server from the CLI or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
+
+You can also provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from your project settings to persist your application data with no manual configuration.
+
 ## Get started
 
 Choose the path that matches what you want to do:

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

@@ -62,6 +62,8 @@ A deploy transitions through **queued → uploading → building → deploying
 
 Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After your first interactive deploy, CI/CD needs two things: an API token and the `.mastra-project.json` file committed to your repository.
 
+> **Tip:** If your code lives on GitHub, the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) gives you push-to-deploy without writing a workflow file. Use the CLI-based CI/CD flow below when you need GitLab, another CI provider, or custom build steps before deploy.
+
 ### Create an API token
 
 1. Run the following command locally:

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

@@ -2,6 +2,8 @@
 
 Studio on Mastra platform is a hosted visual environment for testing agents, running workflows, and inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.
 
+You can deploy Studio from the CLI as shown below, or link a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
+
 ## Quickstart
 
 1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.

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

@@ -44,12 +44,16 @@ then interact with elements using their refs (e.g., @e5).`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
+**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset.
+
 **excludeTools** (`BrowserToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
 
 ## Tools
 
 `AgentBrowser` provides 16 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
 
+When `recording` is configured, `AgentBrowser` also adds the alpha `browser_record` and `browser_record_caption` tools. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording).
+
 ### Core tools
 
 | Tool                 | Description                                                                           |

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

@@ -61,11 +61,17 @@ Use stagehand_extract to get data from pages.`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
+**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset.
+
 **excludeTools** (`StagehandToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
 
 ## Tools
 
-`StagehandBrowser` provides 7 AI-powered tools for browser automation:
+`StagehandBrowser` provides 7 AI-powered tools for browser automation.
+
+When `recording` is configured, `StagehandBrowser` also adds the alpha `browser_record` and `browser_record_caption` tools. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording).
+
+Core tools:
 
 | Tool                   | Description                                                                           |
 | ---------------------- | ------------------------------------------------------------------------------------- |

package/.docs/reference/client-js/agents.md

@@ -522,6 +522,26 @@ response.processDataStream({
 })
 ```
 
+### Shape client tool output for the model
+
+Client tools support `toModelOutput` to control what the model receives, including multimodal content such as images. Because client tools execute locally, the mapping also runs on the client after `execute` completes. The transformed output is sent back to the server alongside the raw result, so the raw result stays available for storage and application logic.
+
+```typescript
+const screenshotTool = createTool({
+  id: 'takeScreenshot',
+  description: 'Takes a screenshot of the current page',
+  inputSchema: z.object({}),
+  execute: async () => {
+    const base64 = await captureScreenshot()
+    return { ok: true, data: base64 }
+  },
+  toModelOutput: output => ({
+    type: 'content',
+    value: [{ type: 'media', data: output.data, mediaType: 'image/jpeg' }],
+  }),
+})
+```
+
 ### Tracing client tools
 
 When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call, injects a W3C trace carrier into the outgoing tool-call chunk, and ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.

package/.docs/reference/streaming/ChunkType.md

@@ -610,6 +610,36 @@ Contains monitoring and observability data from agent execution. Can include wor
 
 **payload.\[key: string]** (`any`): Additional monitoring and execution data
 
+### goal
+
+Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/agents/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
+
+**type** (`"goal"`): Chunk type identifier
+
+**payload** (`GoalEvaluationPayload`): The result of one goal evaluation
+
+**payload.objective** (`string`): The objective being judged
+
+**payload.iteration** (`number`): Goal evaluations consumed so far (runsUsed after this evaluation)
+
+**payload.maxRuns** (`number`): Max evaluations before the goal stops
+
+**payload.passed** (`boolean`): Whether the goal is judged complete
+
+**payload.status** (`"active" | "paused" | "done"`): The objective status after this evaluation
+
+**payload.results** (`ScorerResult[]`): Individual scorer results
+
+**payload.reason** (`string`): Judge feedback or stop reason
+
+**payload.duration** (`number`): Total duration of the goal scoring check
+
+**payload.timedOut** (`boolean`): Whether scoring timed out
+
+**payload.maxRunsReached** (`boolean`): Whether the run budget (maxRuns) was reached
+
+**payload.suppressFeedback** (`boolean`): Whether the goal feedback message is suppressed from memory
+
 ### tripwire
 
 Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.

package/.docs/reference/templates/overview.md

@@ -9,6 +9,16 @@ Mastra templates are pre-built project structures that demonstrate specific use
 - **Educational resources**: Learn Mastra patterns through real implementations
 - **Quickstarts**: Bootstrap projects faster than building from scratch
 
+## Available templates
+
+The following templates demonstrate Gateway-first Mastra applications:
+
+- `template-docs-expert`: Answers documentation questions with Mastra Gateway web search, citations, memory, and structured responses.
+- `template-browser-agent`: Uses AgentBrowser to browse, inspect, and interact with web pages.
+- `template-meeting-notes`: Turns Zoom transcripts or uploaded transcripts into structured notes with decisions and action items.
+- `template-company-knowledge`: Indexes Linear and Notion content into pgvector and answers internal knowledge questions.
+- `template-claw-assistant`: Operates a workspace with filesystem, sandbox, browser, and web-search tools.
+
 ## Using templates
 
 ### Installation

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.47
+
+### Patch Changes
+
+- Updated dependencies [[`de66bb0`](https://github.com/mastra-ai/mastra/commit/de66bb040570444c702ce4d8e1e228a5de2949cb), [`67bf8e2`](https://github.com/mastra-ai/mastra/commit/67bf8e206dfe583954d96015cf0d09f7ac50e45f), [`8216d05`](https://github.com/mastra-ai/mastra/commit/8216d0528d866eb9a07f5d4c87ea3bb1e1139b45), [`d18b23c`](https://github.com/mastra-ai/mastra/commit/d18b23c5e29dfc381e73e3c51fcf6c779afd1823), [`5eb94eb`](https://github.com/mastra-ai/mastra/commit/5eb94ebcf66d4e28c9e26d5821ac93379bab20a0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`f9ee2ac`](https://github.com/mastra-ai/mastra/commit/f9ee2ac661af584e61bc063ac208c9035cd752ef), [`c853d53`](https://github.com/mastra-ai/mastra/commit/c853d535d2df84ab89db1adb4c28900c54c9a2d2), [`d8df1f8`](https://github.com/mastra-ai/mastra/commit/d8df1f8e947e1966c9d4e54713df56d0d0d65226), [`9192ddb`](https://github.com/mastra-ai/mastra/commit/9192ddbced8949113b30de444cbe763f075b59f5), [`ae96523`](https://github.com/mastra-ai/mastra/commit/ae965231f562d9766b0c90c49a69fc68acaa031c), [`17d5a92`](https://github.com/mastra-ai/mastra/commit/17d5a9211aa293b4d4418de3de70dc0394d58101), [`5573693`](https://github.com/mastra-ai/mastra/commit/5573693b589822250e20dfe6cf66e9ff3bc96da8), [`ec4da8a`](https://github.com/mastra-ai/mastra/commit/ec4da8a09e0d2ab452c6ee2c786042ea826b77e5), [`adc44e1`](https://github.com/mastra-ai/mastra/commit/adc44e13c7e570b91e86b20ea7556e61d819db31), [`ed346c0`](https://github.com/mastra-ai/mastra/commit/ed346c0bee2d8496690a4e538bfba1e46894660f), [`c9ce1b2`](https://github.com/mastra-ai/mastra/commit/c9ce1b28d10871110648f9d7b6d76e880b9fa999), [`3ef01fd`](https://github.com/mastra-ai/mastra/commit/3ef01fd130b53d5bd4f828beb174e516a2eb1158), [`245a9a3`](https://github.com/mastra-ai/mastra/commit/245a9a315705fce17ddd980f78a92504b6615c4a), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`38b5de8`](https://github.com/mastra-ai/mastra/commit/38b5de8e5d1d41a69522addf53d96f4b3a1d5bf0), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`dd6a66e`](https://github.com/mastra-ai/mastra/commit/dd6a66ea0b32e0dea8059aec6b35d151e2c87dc4), [`d785c59`](https://github.com/mastra-ai/mastra/commit/d785c593b67fcb4cdc4fab9fdbde5f3b7665efc0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`8b984f4`](https://github.com/mastra-ai/mastra/commit/8b984f4361c202270ceb69257185c4756c9a7c56), [`bf08402`](https://github.com/mastra-ai/mastra/commit/bf084022374fa5d06ca70ed67a86dd64e379071b), [`81fe587`](https://github.com/mastra-ai/mastra/commit/81fe587275035715c1720ddf3fee0505cf053036), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`403c438`](https://github.com/mastra-ai/mastra/commit/403c438e417278989ce247233d2c465b8d902cdd), [`f8ba195`](https://github.com/mastra-ai/mastra/commit/f8ba1954e27ee2b20586cc6cd9cf13c002c232f2)]:
+  - @mastra/core@1.43.0
+
 ## 1.1.46
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.46",
+  "version": "1.1.48",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,15 +28,15 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.42.0",
+    "@mastra/core": "1.43.0",
     "@mastra/mcp": "^1.10.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
     "@types/jsdom": "^21.1.7",
-    "@types/node": "22.19.15",
-    "@vitest/coverage-v8": "4.1.5",
-    "@vitest/ui": "4.1.5",
+    "@types/node": "22.19.21",
+    "@vitest/coverage-v8": "4.1.8",
+    "@vitest/ui": "4.1.8",
     "@wong2/mcp-cli": "^2.0.0",
     "cross-env": "^10.1.0",
     "eslint": "^10.4.1",
@@ -44,10 +44,10 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.79",
-    "@internal/lint": "0.0.104",
-    "@mastra/core": "1.42.0"
+    "vitest": "4.1.8",
+    "@internal/types-builder": "0.0.80",
+    "@internal/lint": "0.0.105",
+    "@mastra/core": "1.43.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {