@mastra/mcp-docs-server 1.1.41-alpha.0 → 1.1.42-alpha.2

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

@@ -0,0 +1,97 @@
+# Agent Builder overview
+
+> **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 lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
+
+- [**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.
+- [**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.
+- [**Skill registries**](https://mastra.ai/docs/agent-builder/skill-registries): Browse and install community skills from opt-in registries.
+- [**Deploying**](https://mastra.ai/docs/agent-builder/deploying): Swap local primitives for cloud-backed storage, filesystems, and sandboxes.
+
+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).
+
+## Get started
+
+Install `@mastra/editor` alongside a storage adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/editor @mastra/libsql
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/editor @mastra/libsql
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/editor @mastra/libsql
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/editor @mastra/libsql
+```
+
+Wire the Agent Builder onto a `Mastra` instance:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { MastraEditor } from '@mastra/editor'
+import { createBuilderAgent } from '@mastra/editor/ee'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  agents: { builderAgent: createBuilderAgent() },
+  editor: new MastraEditor({
+    builder: {
+      enabled: true,
+      configuration: {
+        agent: {
+          memory: { observationalMemory: true },
+        },
+      },
+    },
+  }),
+})
+```
+
+Start the dev server:
+
+```bash
+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:
+
+```typescript
+new MastraEditor({
+  builder: {
+    enabled: false,
+  },
+})
+```
+
+Omitting the `builder` field has the same effect.

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

@@ -0,0 +1,31 @@
+# Skill registries
+
+> **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.
+
+Registries let the Agent Builder browse and install community skills directly from the UI. All registries are opt-in. When no registry is enabled, the Builder hides registry browse UI entirely.
+
+## Quickstart
+
+Enable the [skills.sh](https://skills.sh) registry:
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    registries: {
+      skillsSh: { enabled: true },
+    },
+  },
+})
+```
+
+The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent.
+
+> **Note:** See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
+
+## 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`.

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

@@ -0,0 +1,60 @@
+# Workspace
+
+> **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.
+
+A [workspace](https://mastra.ai/docs/workspace/overview) gives agents filesystem access, command execution, and skill loading. The Agent Builder pins a default workspace onto every new agent through `builder.configuration.agent.workspace`. End users can still override the workspace per agent through the Builder UI.
+
+## Quickstart
+
+Pin an inline workspace snapshot as the Builder default:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  editor: new MastraEditor({
+    builder: {
+      enabled: true,
+      configuration: {
+        agent: {
+          workspace: {
+            type: 'inline',
+            config: {
+              name: 'project-workspace',
+              filesystem: {
+                provider: 'local',
+                config: { basePath: './workspace' },
+              },
+            },
+          },
+        },
+      },
+    },
+  }),
+})
+```
+
+The Builder derives a deterministic id from the inline config and persists the snapshot, so identical inline configs are deduplicated across agents.
+
+## Workspace references
+
+`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.
+
+See the [StorageWorkspaceRef reference](https://mastra.ai/reference/editor/storage-workspace-ref) for both variants.
+
+## Filesystem and sandbox
+
+A workspace combines a `filesystem` (file tools) and an optional `sandbox` (command execution). For local development, point both at the same directory so files written through the filesystem are immediately visible to commands in the sandbox.
+
+For cloud deployments, swap `LocalFilesystem` / `LocalSandbox` for managed providers (e.g., S3, E2B). See [Deploying](https://mastra.ai/docs/agent-builder/deploying) for the cloud-swap pattern.
+
+## 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.

package/.docs/reference/client-js/agent-builder.md

@@ -0,0 +1,161 @@
+# Agent Builder API
+
+The Agent Builder API provides methods to interact with [Agent Builder](https://mastra.ai/docs/agent-builder/overview) actions on the server. Each action is a workflow exposed under `/agent-builder/:actionId/*`. The Builder must be enabled on the server via `MastraEditor.builder.enabled`, with a valid `MASTRA_EE_LICENSE` in production.
+
+## Getting all actions
+
+Retrieve a record of available Agent Builder actions:
+
+```typescript
+const actions = await mastraClient.getAgentBuilderActions()
+```
+
+Returns a `Record<string, WorkflowInfo>` keyed by action ID.
+
+## Working with a specific action
+
+Get an instance of a specific action by its ID:
+
+```typescript
+const action = mastraClient.getAgentBuilderAction('create-agent')
+```
+
+## Action methods
+
+### `details()`
+
+Retrieve metadata about an Agent Builder action:
+
+```typescript
+const info = await action.details()
+```
+
+### `createRun()`
+
+Create a new run for this action and receive a `runId`. Use the returned id with `startActionRun()`, `stream()`, `resume()`, or `observeStream()`.
+
+```typescript
+const { runId } = await action.createRun()
+```
+
+You can also pass an explicit `runId`:
+
+```typescript
+const { runId } = await action.createRun({ runId: 'my-run-id' })
+```
+
+### `startAsync()`
+
+Start the action and wait for completion. Returns the final `AgentBuilderActionResult` with `success`, `applied`, `branchName`, `message`, `validationResults`, `error`, `errors`, and `stepResults`.
+
+```typescript
+const result = await action.startAsync({
+  inputData: { agentName: 'support-bot' },
+})
+```
+
+Pass an existing `runId` as the second argument to start a previously created run:
+
+```typescript
+const { runId } = await action.createRun()
+const result = await action.startAsync({ inputData }, runId)
+```
+
+### `startActionRun()`
+
+Start an existing run without waiting for completion. Returns `{ message }`.
+
+```typescript
+const { runId } = await action.createRun()
+await action.startActionRun({ inputData }, runId)
+```
+
+### `stream()`
+
+Start an existing run and stream progress events as a `ReadableStream<{ type, payload }>`.
+
+```typescript
+const { runId } = await action.createRun()
+const stream = await action.stream({ inputData }, runId)
+
+for await (const event of stream) {
+  console.log(event.type, event.payload)
+}
+```
+
+### `resume()`
+
+Resume a suspended step on a run. Returns `{ message }`.
+
+```typescript
+await action.resume({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeAsync()`
+
+Resume a suspended step and wait for completion. Returns an `AgentBuilderActionResult`.
+
+```typescript
+const result = await action.resumeAsync({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeStream()`
+
+Resume a suspended step and stream subsequent events.
+
+```typescript
+const stream = await action.resumeStream({
+  runId,
+  step: 'review',
+  resumeData: { approved: true },
+})
+```
+
+### `observeStream()`
+
+Attach to an existing run, replaying cached events from the beginning, then continuing with live events. Use this to recover after a page refresh or hot reload.
+
+```typescript
+const stream = await action.observeStream({ runId })
+```
+
+### `observeStreamLegacy()`
+
+Same as `observeStream()` but uses the legacy streaming endpoint. Prefer `observeStream()` for new code.
+
+```typescript
+const stream = await action.observeStreamLegacy({ runId })
+```
+
+### `runs()`
+
+List runs for this action with optional filters.
+
+```typescript
+const runs = await action.runs({ page: 0, perPage: 20 })
+```
+
+Accepts `fromDate`, `toDate`, `page`, `perPage`, `resourceId`, and legacy `limit`/`offset`.
+
+### `runById()`
+
+Fetch a specific run by ID. Use `fields` to limit the returned payload and `withNestedWorkflows` to skip nested workflow data.
+
+```typescript
+const run = await action.runById(runId, {
+  fields: ['result', 'steps'],
+  withNestedWorkflows: false,
+})
+```
+
+### `cancelRun()`
+
+Cancel an in-flight run.
+
+```typescript
+await action.cancelRun(runId)
+```
+
+## Access control
+
+The `/agent-builder/*` routes are gated by the `agent-builder` permission resource. Calling clients need at minimum `agent-builder:read` and `agent-builder:execute`, plus any picker resources the action touches (`stored-agents`, `stored-skills`, `tools`, `workflows`, `memory`). See [Access control](https://mastra.ai/docs/agent-builder/access-control) for the full grant list.

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

@@ -73,6 +73,10 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
+**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
+**getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
 **responses** (`Responses`): Provides OpenAI-style Responses API helpers with \`create()\`, \`retrieve()\`, \`stream()\`, and \`delete()\`.
 
 **conversations** (`Conversations`): Provides conversation helpers with \`create()\`, \`retrieve()\`, \`delete()\`, and \`items.list()\`.

package/.docs/reference/editor/agent-builder/agent-builder-options.md

@@ -0,0 +1,74 @@
+# AgentBuilderOptions
+
+`AgentBuilderOptions` configures the Agent Builder. Pass it as `MastraEditor.builder` to enable the Builder UI, toggle visible surfaces, pin admin defaults, and opt into skill registries.
+
+See the [Configuration](https://mastra.ai/docs/agent-builder/configuration) page for concepts and worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    features: {
+      agent: { browser: false },
+    },
+    configuration: {
+      agent: {
+        memory: { observationalMemory: true },
+        models: {
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
+          ],
+        },
+      },
+    },
+    registries: {
+      skillsSh: { enabled: true },
+    },
+  },
+})
+```
+
+## Properties
+
+**enabled** (`boolean`): Master switch. When false, the Builder UI is disabled and \`MastraEditor.resolveBuilder()\` returns undefined. (Default: `true`)
+
+**features** (`{ agent?: AgentFeatures }`): UI toggles. Each key on \`features.agent\` defaults to true when omitted.
+
+**features.agent.tools** (`boolean`): Show the tools tab in the agent editor.
+
+**features.agent.agents** (`boolean`): Show the sub-agents picker in the agent editor.
+
+**features.agent.workflows** (`boolean`): Show the workflows picker in the agent editor.
+
+**features.agent.skills** (`boolean`): Show the skills tab and library for the agent.
+
+**features.agent.memory** (`boolean`): Show the memory configuration in the agent editor.
+
+**features.agent.model** (`boolean`): Show the model picker in the agent editor. When false, the admin-pinned default model applies.
+
+**features.agent.browser** (`boolean`): Show the browser tab. Resolves to true only when a valid browser provider is registered on \`MastraEditor.browsers\`; otherwise it is downgraded to false and a warning is logged.
+
+**features.agent.avatarUpload** (`boolean`): Allow end users to upload an avatar for stored agents.
+
+**features.agent.favorites** (`boolean`): Show favorite agents and skills with per-user state and aggregate counts.
+
+**configuration** (`{ agent?: BuilderAgentDefaults }`): Admin-pinned defaults applied to every Builder-created agent. End users cannot override these values. See the BuilderAgentDefaults reference for the full schema.
+
+**registries** (`{ skillsSh?: { enabled: boolean } }`): Opt-in third-party skill registries. When no registry is enabled, the Builder hides registry browse UI.
+
+**registries.skillsSh** (`{ enabled: boolean }`): Enable the skills.sh registry. When enabled, the Builder shows registry browse UI for skills.sh skills.
+
+**registries.skillsSh.enabled** (`boolean`): Set to \`true\` to opt in. Defaults to \`false\`.
+
+## Related
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — concept and worked examples.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — full schema for `configuration.agent`.
+- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — model allowlist and default model.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — the parent surface that hosts `builder`.

package/.docs/reference/editor/agent-builder/builder-agent-defaults.md

@@ -0,0 +1,77 @@
+# BuilderAgentDefaults
+
+`BuilderAgentDefaults` describes the admin-pinned defaults applied to every agent the Agent Builder produces. Pass it as `builder.configuration.agent`. End users can't override these values from the Builder UI.
+
+See [Configuration](https://mastra.ai/docs/agent-builder/configuration) and [Memory](https://mastra.ai/docs/agent-builder/memory) for worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        memory: { observationalMemory: true },
+        workspace: {
+          type: 'inline',
+          config: {
+            name: 'builder-workspace',
+            filesystem: {
+              provider: 'local',
+              config: { basePath: './workspace' },
+            },
+          },
+        },
+        models: {
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
+          ],
+        },
+        tools: { allowed: ['weather-info'] },
+        agents: { allowed: ['weather-agent'] },
+        workflows: { allowed: ['greet-workflow'] },
+      },
+    },
+  },
+})
+```
+
+## Properties
+
+**memory** (`SerializedMemoryConfig`): Default memory configuration for new agents. Pass \`{ observationalMemory: true }\` to enable long-lived fact extraction. Requires \`Mastra.storage\`. See the SerializedMemoryConfig reference for the full schema.
+
+**workspace** (`StorageWorkspaceRef`): Default workspace reference for new agents. Pass \`{ type: 'inline', config }\` to embed a snapshot, or \`{ type: 'id', workspaceId }\` to point at a workspace registered on \`Mastra.workspace\`. See the StorageWorkspaceRef reference for both variants.
+
+**browser** (`StorageBrowserRef`): Default browser configuration for new agents. Pass \`{ type: 'inline', config: { provider } }\` to attach a registered browser provider. See the StorageBrowserRef reference for the full schema.
+
+**models** (`{ allowed?: ProviderModelEntry[]; default?: DefaultModelEntry }`): Model allowlist and default applied to every Builder-created agent. See the BuilderModels reference for the full schema and validation rules.
+
+**models.allowed** (`ProviderModelEntry[]`): Allowlist of providers and models. Omit to allow every registered model. ProviderModelEntry is a discriminated union (known providers vs. custom).
+
+**models.default** (`DefaultModelEntry`): Pre-selected model on new-agent create. Required when the model picker is hidden. DefaultModelEntry requires \`provider\` and \`modelId\`, with an optional \`kind\`.
+
+**tools** (`{ allowed?: string[] }`): Allowlist of tool IDs visible in the Builder tools picker. Unknown IDs are dropped and surfaced as warnings.
+
+**tools.allowed** (`string[]`): Allowlist of \`tool.id\` values. Omit for unrestricted, pass \`\[]\` to lock the picker down, pass \`\[...ids]\` to restrict to the listed tools.
+
+**agents** (`{ allowed?: string[] }`): Allowlist of agent IDs visible in the Builder sub-agents picker. Unknown IDs are dropped and surfaced as warnings.
+
+**agents.allowed** (`string[]`): Allowlist of \`Agent.id\` values. Omit for unrestricted, pass \`\[]\` to lock the picker down, pass \`\[...ids]\` to restrict to the listed agents.
+
+**workflows** (`{ allowed?: string[] }`): Allowlist of workflow IDs visible in the Builder workflows picker. Unknown IDs are dropped and surfaced as warnings.
+
+**workflows.allowed** (`string[]`): Allowlist of \`workflow\.id\` values. Omit for unrestricted, pass \`\[]\` to lock the picker down, pass \`\[...ids]\` to restrict to the listed workflows.
+
+## Related
+
+- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the parent options object.
+- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — admin-facing model allowlist and default.
+- [SerializedMemoryConfig](https://mastra.ai/reference/memory/serialized-memory-config) — memory shape for new agents.
+- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref) — workspace reference shape.
+- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — browser reference shape.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — concept and worked examples.

package/.docs/reference/editor/agent-builder/builder-models.md

@@ -0,0 +1,64 @@
+# builder.configuration.agent.models
+
+`builder.configuration.agent.models` is the admin-facing model policy input on `AgentBuilderOptions`. It controls which providers and models the Agent Builder exposes, and which model is pre-selected on new-agent create.
+
+See [Model policy](https://mastra.ai/docs/agent-builder/model-policy) for concepts and worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+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' },
+          ],
+        },
+      },
+    },
+  },
+})
+```
+
+## Properties
+
+**allowed** (`ProviderModelEntry[]`): Allowlist of providers and models. Omit to allow every registered model. When non-empty, only the listed entries are selectable in the Builder.
+
+**allowed.provider** (`Provider`): Provider id from the generated provider registry (for example, \`openai\`, \`anthropic\`).
+
+**allowed.modelId** (`ModelForProvider<Provider>`): Specific model id for that provider. Omit to allow every model under the provider.
+
+**allowed.kind** (`'custom'`): Discriminant marking this entry as a gateway or self-hosted provider not in the registry.
+
+**allowed.provider** (`string`): Provider id for the custom provider.
+
+**allowed.modelId** (`string`): Specific model id under the custom provider. Omit to allow every model under it.
+
+**default** (`DefaultModelEntry`): Pre-selected model on new-agent create. Same shape as \`ProviderModelEntry\`, but \`modelId\` is required. Must satisfy the \`allowed\` list when set.
+
+**default.provider** (`Provider | string`): Provider id. Use a \`Provider\` literal for known providers, or any \`string\` with \`kind: 'custom'\`.
+
+**default.modelId** (`string`): Required model id. Points at a specific model, not a whole provider.
+
+**default.kind** (`'custom'`): Set to \`custom\` when targeting a provider that isn't in the generated registry.
+
+## Validation rules
+
+Mastra validates the admin policy at server boot. Violations surface as warnings on `GET /editor/builder/settings.modelPolicyWarnings`.
+
+- `allowed` empty or omitted: no restriction. Every registered model is available.
+- When `allowed` is non-empty and a `default` is set: `default` must satisfy `isModelAllowed(allowed, default)`. A `default` that fails this check is dropped and surfaced as a warning.
+- To hide the end-user model picker, set `features.agent.model: false` in [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options). When the picker is hidden, provide a `default` so new agents resolve a model.
+
+## Related
+
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — parent object containing `models`.
+- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the top-level Builder options.
+- [Model policy](https://mastra.ai/docs/agent-builder/model-policy) — concept and worked examples.

package/.docs/reference/editor/blob-store-provider.md

@@ -0,0 +1,59 @@
+# BlobStoreProvider
+
+`BlobStoreProvider` is the interface a package implements to register a blob store with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). Blob stores hold content-addressable skill blobs and other large artifacts produced by the editor.
+
+The built-in `storage` provider uses the configured storage backend's `blobs` domain. External providers (for example, S3) are supplied via `MastraEditorConfig.blobStores`.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { s3BlobStoreProvider } from '@mastra/s3'
+
+new MastraEditor({
+  blobStores: {
+    [s3BlobStoreProvider.id]: s3BlobStoreProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"storage"\`, \`"s3"\`).
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createBlobStore** (`(config: TConfig) => BlobStore | Promise<BlobStore>`): Create a runtime \`BlobStore\` instance from the stored config. Called when the editor resolves a blob store via \`MastraEditor.resolveBlobStore(providerId, config)\`.
+
+## Implementing a provider
+
+```typescript
+import type { BlobStore, BlobStoreProvider } from '@mastra/core/editor'
+
+export const myBlobStoreProvider: BlobStoreProvider<{ bucket: string; region: string }> = {
+  id: 'my-blob-store',
+  name: 'My Blob Store',
+  description: 'Object-store-backed blob storage.',
+  configSchema: {
+    type: 'object',
+    required: ['bucket', 'region'],
+    properties: {
+      bucket: { type: 'string' },
+      region: { type: 'string' },
+    },
+  },
+  async createBlobStore(config): Promise<BlobStore> {
+    return createMyBlobStore({ bucket: config.bucket, region: config.region })
+  },
+}
+```
+
+When no `providerId` is passed to `MastraEditor.resolveBlobStore()`, the editor falls back to the storage backend's `blobs` domain.
+
+## Related
+
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry and `resolveBlobStore()` method.