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

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.

package/.docs/reference/editor/browser-provider.md

@@ -0,0 +1,75 @@
+# BrowserProvider
+
+`BrowserProvider` is the interface a package implements to register a browser with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createBrowser(config)` at agent hydration time, using the `provider` id from the stored [`StorageBrowserRef`](https://mastra.ai/reference/editor/storage-browser-ref) as the lookup key.
+
+There are no built-in browser providers. To use the `browser` feature in the Agent Builder, register a provider package (for example, `@mastra/stagehand`).
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { stagehandBrowserProvider } from '@mastra/stagehand'
+
+new MastraEditor({
+  browsers: {
+    [stagehandBrowserProvider.id]: stagehandBrowserProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"stagehand"\`). Must match \`StorageBrowserConfig.provider\` on every stored agent that uses this provider.
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description shown in the Agent Builder browser picker.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createBrowser** (`(config: TConfig) => MastraBrowser | Promise<MastraBrowser>`): Create a runtime \`MastraBrowser\` instance from the stored config. Called once per agent hydration; the resulting instance is cached alongside the agent.
+
+## Implementing a provider
+
+```typescript
+import type { BrowserProvider, MastraBrowser } from '@mastra/core/editor'
+
+export const myBrowserProvider: BrowserProvider<{ apiKey: string }> = {
+  id: 'my-browser',
+  name: 'My Browser',
+  description: 'Headless browser for agent use.',
+  configSchema: {
+    type: 'object',
+    properties: {
+      apiKey: { type: 'string' },
+    },
+    required: ['apiKey'],
+  },
+  async createBrowser(config): Promise<MastraBrowser> {
+    // construct and return a MastraBrowser instance
+    return createMastraBrowser({ apiKey: config.apiKey })
+  },
+}
+```
+
+Once registered, admins can pin the provider as a Builder default via [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults):
+
+```typescript
+new MastraEditor({
+  browsers: { [myBrowserProvider.id]: myBrowserProvider },
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        browser: { type: 'inline', config: { provider: 'my-browser' } },
+      },
+    },
+  },
+})
+```
+
+## Related
+
+- [Browser](https://mastra.ai/docs/agent-builder/browser) — concept and worked examples.
+- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — stored configuration consumed by `createBrowser`.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry.

package/.docs/reference/editor/filesystem-provider.md

@@ -0,0 +1,62 @@
+# FilesystemProvider
+
+`FilesystemProvider` is the interface a package implements to register a filesystem with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createFilesystem(config)` at workspace hydration time, using the `provider` id from the stored [`StorageWorkspaceRef`](https://mastra.ai/reference/editor/storage-workspace-ref) filesystem config as the lookup key.
+
+The built-in `local` filesystem provider is auto-registered. External providers (for example, S3 or GCS) are supplied via `MastraEditorConfig.filesystems`.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { s3FilesystemProvider } from '@mastra/s3'
+
+new MastraEditor({
+  filesystems: {
+    [s3FilesystemProvider.id]: s3FilesystemProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"local"\`, \`"s3"\`). Must match \`StorageFilesystemConfig.provider\` on every stored workspace that uses this provider.
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description shown in the workspace filesystem picker.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createFilesystem** (`(config: TConfig) => WorkspaceFilesystem | Promise<WorkspaceFilesystem>`): Create a runtime \`WorkspaceFilesystem\` instance from the stored config. Called at workspace hydration time.
+
+## Implementing a provider
+
+```typescript
+import type { FilesystemProvider, WorkspaceFilesystem } from '@mastra/core/editor'
+
+export const myFilesystemProvider: FilesystemProvider<{ bucket: string; region: string }> = {
+  id: 'my-fs',
+  name: 'My Filesystem',
+  description: 'Object-store-backed filesystem.',
+  configSchema: {
+    type: 'object',
+    required: ['bucket', 'region'],
+    properties: {
+      bucket: { type: 'string' },
+      region: { type: 'string' },
+    },
+  },
+  async createFilesystem(config): Promise<WorkspaceFilesystem> {
+    return createMyFilesystem({ bucket: config.bucket, region: config.region })
+  },
+}
+```
+
+Once registered, admins can reference the provider from an inline workspace config or a stored [`StorageWorkspaceRef`](https://mastra.ai/reference/editor/storage-workspace-ref).
+
+## Related
+
+- [Workspace](https://mastra.ai/docs/agent-builder/workspace) — concept and worked examples.
+- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref) — stored configuration consumed by `createFilesystem`.
+- [SandboxProvider](https://mastra.ai/reference/editor/sandbox-provider) — sibling provider for command execution.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry.

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

@@ -39,6 +39,50 @@ export const mastra = new Mastra({
 
 **blobStores** (`Record<string, BlobStoreProvider>`): Blob storage providers for binary data (for example, S3). Falls back to the Mastra storage blob store if no provider is specified. (Default: `{}`)
 
+**browsers** (`Record<string, BrowserProvider>`): Browser providers for agent browser access (for example, Stagehand). No built-ins — required when \`builder.features.agent.browser\` is enabled. See the BrowserProvider reference for the provider interface. (Default: `{}`)
+
+**builder** (`AgentBuilderOptions`): Agent Builder configuration. See the AgentBuilderOptions reference. Omit or set \`enabled: false\` to disable the Builder.
+
+### Provider interfaces
+
+Each provider field above takes a record keyed by provider id. See the per-provider reference pages for the implementation shape:
+
+- [ProcessorProvider](https://mastra.ai/reference/editor/processor-provider)
+- [FilesystemProvider](https://mastra.ai/reference/editor/filesystem-provider)
+- [SandboxProvider](https://mastra.ai/reference/editor/sandbox-provider)
+- [BlobStoreProvider](https://mastra.ai/reference/editor/blob-store-provider)
+- [BrowserProvider](https://mastra.ai/reference/editor/browser-provider)
+
+## Agent Builder
+
+The `builder` field enables the [Agent Builder](https://mastra.ai/docs/agent-builder/overview), a browser-based UI for creating and editing stored agents. See:
+
+- [Agent Builder overview](https://mastra.ai/docs/agent-builder/overview) — concepts and getting started.
+- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — full options schema.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — admin-pinned defaults for new agents.
+- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — model allowlist and default model.
+
+### Registering the Builder agent
+
+The Builder UI runs against an agent created by the `createBuilderAgent()` factory from `@mastra/editor/ee`. Import the factory, invoke it, and register the returned agent under `agents` on your Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+import { createBuilderAgent } from '@mastra/editor/ee'
+
+export const mastra = new Mastra({
+  agents: { builderAgent: createBuilderAgent() },
+  editor: new MastraEditor({
+    builder: { enabled: true },
+  }),
+})
+```
+
+The key name (`builderAgent`) is conventional — any key works. The `@mastra/editor/ee` subpath is gated by the Mastra Enterprise Edition license at runtime.
+
+See the [Agent Builder overview](https://mastra.ai/docs/agent-builder/overview) for the full setup checklist.
+
 ## Namespaces
 
 The editor exposes namespaces for managing different entity types. Access them from any Mastra instance with `mastra.getEditor()` and call the CRUD methods directly in application code, or rely on the Mastra server routes that use them under the hood.

package/.docs/reference/editor/processor-provider.md

@@ -0,0 +1,64 @@
+# ProcessorProvider
+
+`ProcessorProvider` is the interface a package implements to register a configurable processor with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). Processor providers serve two purposes:
+
+1. **Discovery** — the UI uses `info`, `configSchema`, and `availablePhases` to render configuration forms.
+2. **Runtime** — the editor calls `createProcessor(config)` during agent hydration to instantiate processors from stored configuration.
+
+Providers are supplied via `MastraEditorConfig.processorProviders`.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { moderationProcessorProvider } from '@mastra/processors/moderation'
+
+new MastraEditor({
+  processorProviders: {
+    moderation: moderationProcessorProvider,
+  },
+})
+```
+
+## Properties
+
+**info** (`ProcessorProviderInfo`): Metadata about the provider.
+
+**info.id** (`string`): Unique identifier (for example, \`"moderation"\`, \`"token-limiter"\`).
+
+**info.name** (`string`): Human-readable name.
+
+**info.description** (`string`): Short description of the provider.
+
+**configSchema** (`ZodSchema`): Zod schema describing the configuration this provider accepts. Used by the UI to render a form. The validated config object is passed to \`createProcessor()\`.
+
+**availablePhases** (`ProcessorPhase[]`): Phases this provider's processors support. One or more of \`'processInput'\`, \`'processInputStep'\`, \`'processOutputStream'\`, \`'processOutputResult'\`, \`'processOutputStep'\`.
+
+**createProcessor** (`(config: Record<string, unknown>) => Processor`): Create a \`Processor\` instance from the validated configuration. Called during agent hydration to resolve stored processor configs into live instances.
+
+## Implementing a provider
+
+```typescript
+import type { ProcessorProvider } from '@mastra/core/processor-provider'
+import { z } from 'zod'
+import { MyProcessor } from './my-processor-impl'
+
+export const myProcessorProvider: ProcessorProvider = {
+  info: {
+    id: 'my-processor',
+    name: 'My Processor',
+    description: 'Filters output for sensitive content.',
+  },
+  configSchema: z.object({
+    threshold: z.number().min(0).max(1),
+  }),
+  availablePhases: ['processOutputStream', 'processOutputResult'],
+  createProcessor(config) {
+    return new MyProcessor(config as { threshold: number })
+  },
+}
+```
+
+## Related
+
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry.

package/.docs/reference/editor/sandbox-provider.md

@@ -0,0 +1,61 @@
+# SandboxProvider
+
+`SandboxProvider` is the interface a package implements to register a sandbox with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createSandbox(config)` at workspace hydration time, using the `provider` id from the stored [`StorageWorkspaceRef`](https://mastra.ai/reference/editor/storage-workspace-ref) sandbox config as the lookup key.
+
+The built-in `local` sandbox provider is auto-registered. External providers (for example, E2B) are supplied via `MastraEditorConfig.sandboxes`.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { e2bSandboxProvider } from '@mastra/e2b'
+
+new MastraEditor({
+  sandboxes: {
+    [e2bSandboxProvider.id]: e2bSandboxProvider,
+  },
+})
+```
+
+## Properties
+
+**id** (`string`): Unique provider identifier (for example, \`"local"\`, \`"e2b"\`). Must match \`StorageSandboxConfig.provider\` on every stored workspace that uses this provider.
+
+**name** (`string`): Human-readable name for UI display.
+
+**description** (`string`): Short description shown in the workspace sandbox picker.
+
+**configSchema** (`Record<string, unknown>`): JSON Schema describing provider-specific configuration. Used by the UI to render config forms.
+
+**createSandbox** (`(config: TConfig) => WorkspaceSandbox | Promise<WorkspaceSandbox>`): Create a runtime \`WorkspaceSandbox\` instance from the stored config. Called at workspace hydration time.
+
+## Implementing a provider
+
+```typescript
+import type { SandboxProvider, WorkspaceSandbox } from '@mastra/core/editor'
+
+export const mySandboxProvider: SandboxProvider<{ apiKey: string }> = {
+  id: 'my-sandbox',
+  name: 'My Sandbox',
+  description: 'Cloud sandbox for command execution.',
+  configSchema: {
+    type: 'object',
+    required: ['apiKey'],
+    properties: {
+      apiKey: { type: 'string' },
+    },
+  },
+  async createSandbox(config): Promise<WorkspaceSandbox> {
+    return createMySandbox({ apiKey: config.apiKey })
+  },
+}
+```
+
+Once registered, admins can reference the provider from an inline workspace config or a stored [`StorageWorkspaceRef`](https://mastra.ai/reference/editor/storage-workspace-ref).
+
+## Related
+
+- [Workspace](https://mastra.ai/docs/agent-builder/workspace) — concept and worked examples.
+- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref) — stored configuration consumed by `createSandbox`.
+- [FilesystemProvider](https://mastra.ai/reference/editor/filesystem-provider) — sibling provider for file access.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — provider registry.

package/.docs/reference/editor/storage-browser-ref.md

@@ -0,0 +1,80 @@
+# StorageBrowserRef
+
+`StorageBrowserRef` is the inline browser configuration attached to a stored agent. The `provider` id is resolved at hydration time against the [`BrowserProvider`](https://mastra.ai/reference/editor/browser-provider) registered on [`MastraEditor.browsers`](https://mastra.ai/reference/editor/mastra-editor).
+
+It is the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { stagehandBrowserProvider } from '@mastra/stagehand'
+
+new MastraEditor({
+  browsers: { [stagehandBrowserProvider.id]: stagehandBrowserProvider },
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        browser: {
+          type: 'inline',
+          config: {
+            provider: 'stagehand',
+            headless: true,
+            viewport: { width: 1280, height: 720 },
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+## Type
+
+```typescript
+type StorageBrowserRef = { type: 'inline'; config: StorageBrowserConfig }
+```
+
+There is no `{ type: 'id' }` variant for browsers — they are always inlined.
+
+## Properties
+
+**type** (`'inline'`): Discriminant. Must be the literal \`"inline"\`.
+
+**config** (`StorageBrowserConfig`): Provider id and per-instance browser configuration. See the section below.
+
+## `StorageBrowserConfig`
+
+The shape embedded under `config`. Defined in `@mastra/core/storage`.
+
+**provider** (`string`): Provider identifier (for example, \`"stagehand"\`). Must match a \`BrowserProvider.id\` registered on \`MastraEditor.browsers\`. There are no built-in providers.
+
+**headless** (`boolean`): Run the browser in headless mode (no visible UI). (Default: `true`)
+
+**viewport** (`{ width: number; height: number }`): Browser viewport dimensions. Controls window size and how pages render.
+
+**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
+
+**screencast** (`ScreencastOptions`): Screencast options for streaming browser frames to the UI.
+
+**screencast.format** (`'jpeg' | 'png'`): Image format.
+
+**screencast.quality** (`number`): JPEG quality 0–100.
+
+**screencast.maxWidth** (`number`): Max width in pixels.
+
+**screencast.maxHeight** (`number`): Max height in pixels.
+
+**screencast.everyNthFrame** (`number`): Capture every Nth frame.
+
+## Hydration
+
+`StorageBrowserRef` is resolved lazily on `mastra.editor.agent.getById()`. The editor looks up `config.provider` on `MastraEditor.browsers` and calls `provider.createBrowser(config)`. If the provider is not registered, the editor logs a warning and returns `undefined` — the agent still loads, but without a browser.
+
+## Related
+
+- [Browser](https://mastra.ai/docs/agent-builder/browser) — concept and worked examples.
+- [BrowserProvider](https://mastra.ai/reference/editor/browser-provider) — implementer-facing provider interface.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — where this type is pinned as the Builder default.
+- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref) — sibling reference type for workspace configuration.

package/.docs/reference/editor/storage-workspace-ref.md

@@ -0,0 +1,93 @@
+# StorageWorkspaceRef
+
+`StorageWorkspaceRef` is the discriminated union used to attach a workspace to a stored agent. It either points at a workspace registered on the Mastra runtime by ID, or embeds a workspace snapshot inline.
+
+It is the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+// Variant 1 — reference a runtime workspace by id
+new MastraEditor({
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        workspace: { type: 'id', workspaceId: 'builder-workspace' },
+      },
+    },
+  },
+})
+
+// Variant 2 — inline a workspace snapshot
+new MastraEditor({
+  builder: {
+    enabled: true,
+    configuration: {
+      agent: {
+        workspace: {
+          type: 'inline',
+          config: {
+            name: 'inline-builder-workspace',
+            filesystem: {
+              provider: 'local',
+              config: { basePath: './agent-files' },
+            },
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+## Variants
+
+**{ type: 'id'; workspaceId: string }** (`IdRef`): Reference a workspace registered on the Mastra runtime via \`new Mastra({ workspace })\` or \`mastra.addWorkspace()\`. The id is the join key between admin config, stored agent record, and hydration.
+
+**{ type: 'id'; workspaceId: string }.type** (`'id'`): Discriminant. Must be the literal \`"id"\`.
+
+**{ type: 'id'; workspaceId: string }.workspaceId** (`string`): Id of a workspace registered on the Mastra runtime. Used by the Builder to snapshot, persist, and later hydrate the workspace.
+
+**{ type: 'inline'; config: StorageWorkspaceSnapshotType }** (`InlineRef`): Embed a workspace snapshot directly. The Builder derives a deterministic id of the form \`inline-\<sha256(config)\[:12]>\` and persists the snapshot, so identical inline configs are deduplicated across agents.
+
+**{ type: 'inline'; config: StorageWorkspaceSnapshotType }.type** (`'inline'`): Discriminant. Must be the literal \`"inline"\`.
+
+**{ type: 'inline'; config: StorageWorkspaceSnapshotType }.config** (`StorageWorkspaceSnapshotType`): Serialized workspace configuration (filesystem, sandbox, mounts, search, skills, tools). See the \`StorageWorkspaceSnapshotType\` section below for the field list.
+
+## `StorageWorkspaceSnapshotType`
+
+The shape embedded under `{ type: 'inline', config }`. Defined in `@mastra/core/storage`.
+
+**name** (`string`): Display name of the workspace.
+
+**description** (`string`): Purpose description shown in the workspace listing.
+
+**filesystem** (`StorageFilesystemConfig`): Primary filesystem configuration. \`provider\` must match an id registered on \`MastraEditor.filesystems\` (built-in: \`local\`).
+
+**sandbox** (`StorageSandboxConfig`): Sandbox configuration. \`provider\` must match an id registered on \`MastraEditor.sandboxes\` (built-in: \`local\`).
+
+**mounts** (`Record<string, StorageFilesystemConfig>`): Additional filesystems mounted on the workspace, keyed by mount path.
+
+**search** (`StorageSearchConfig`): Search configuration (vector provider, embedder, BM25 settings).
+
+**skills** (`string[]`): Skill entity IDs assigned to this workspace.
+
+**tools** (`StorageWorkspaceToolsConfig`): Workspace tool configuration (allowlists, defaults).
+
+**autoSync** (`boolean`): Auto-sync between filesystem and sandbox. (Default: `false`)
+
+**operationTimeout** (`number`): Timeout for individual operations in milliseconds.
+
+## Hydration
+
+`StorageWorkspaceRef` is resolved lazily on `mastra.editor.agent.getById()`, not on `list()`. The editor looks up filesystem and sandbox providers on `MastraEditor.filesystems` / `MastraEditor.sandboxes` and materializes a runtime `Workspace`. Missing providers surface as a warning and the workspace is omitted.
+
+## Related
+
+- [Workspace](https://mastra.ai/docs/agent-builder/workspace) — concept and worked examples.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — where this type is pinned as the Builder default.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — registers filesystem and sandbox providers.
+- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — sibling reference type for browser configuration.

package/.docs/reference/evals/create-scorer.md

@@ -49,6 +49,8 @@ const scorer = createScorer({
 
 **judge.instructions** (`string`): System prompt/instructions for the LLM.
 
+**judge.jsonPromptInjection** (`boolean`): When true, inject the JSON schema into the prompt instead of using the provider's native \`response\_format\` API. Set this for models that don't support native structured output (e.g. some Groq Llama models) to avoid a wasted 400 call.
+
 **type** (`string`): Type specification for input/output. Use 'agent' for automatic agent types. For custom types, use the generic approach instead.
 
 **prepareRun** (`(run: ScorerRun) => ScorerRun | Promise<ScorerRun>`): Transform the scorer run data before the pipeline executes. Use this to filter messages, limit context size, or drop fields the scorer doesn't need. The \[\`filterRun()\`]\(/reference/evals/filter-run) utility creates this function from declarative options. Can be async.

package/.docs/reference/index.md

@@ -47,6 +47,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser)
 - [create-mastra](https://mastra.ai/reference/cli/create-mastra)
 - [mastra](https://mastra.ai/reference/cli/mastra)
+- [Agent Builder API](https://mastra.ai/reference/client-js/agent-builder)
 - [Agents API](https://mastra.ai/reference/client-js/agents)
 - [Conversations API](https://mastra.ai/reference/client-js/conversations)
 - [Error Handling](https://mastra.ai/reference/client-js/error-handling)
@@ -94,8 +95,18 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Deployer](https://mastra.ai/reference/deployer)
 - [Netlify](https://mastra.ai/reference/deployer/netlify)
 - [Vercel](https://mastra.ai/reference/deployer/vercel)
+- [BlobStoreProvider](https://mastra.ai/reference/editor/blob-store-provider)
 - [MastraEditor Class](https://mastra.ai/reference/editor/mastra-editor)
+- [ProcessorProvider](https://mastra.ai/reference/editor/processor-provider)
 - [ToolProvider](https://mastra.ai/reference/editor/tool-provider)
+- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options)
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults)
+- [Models default](https://mastra.ai/reference/editor/agent-builder/builder-models)
+- [BrowserProvider](https://mastra.ai/reference/editor/browser-provider)
+- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref)
+- [FilesystemProvider](https://mastra.ai/reference/editor/filesystem-provider)
+- [SandboxProvider](https://mastra.ai/reference/editor/sandbox-provider)
+- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref)
 - [createScorer()](https://mastra.ai/reference/evals/create-scorer)
 - [filterRun()](https://mastra.ai/reference/evals/filter-run)
 - [MastraScorer](https://mastra.ai/reference/evals/mastra-scorer)
@@ -147,6 +158,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)
 - [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
+- [SerializedMemoryConfig](https://mastra.ai/reference/memory/serialized-memory-config)
 - [.cloneThread()](https://mastra.ai/reference/memory/cloneThread)
 - [.createThread()](https://mastra.ai/reference/memory/createThread)
 - [.deleteMessages()](https://mastra.ai/reference/memory/deleteMessages)