@mastra/mcp-docs-server 1.2.13-alpha.0 → 1.2.13-alpha.11

package/.docs/{docs/getting-started → reference}/build-with-ai.md

@@ -2,110 +2,7 @@
 
 # Build with AI
 
-AI agents may not have up-to-date knowledge about Mastra's APIs, patterns, and best practices. These resources give your AI tools direct access to current Mastra documentation, enabling them to generate accurate code and help you build faster.
-
-To give your agent access to Mastra's documentation, we recommend using **skills**. While the MCP docs server also provides this information, skills will perform better. Use the MCP docs server when you need its tools, e.g. the migration tool.
-
-## Mastra skills
-
-Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things accurately and efficiently. Mastra skills contain setup instructions, best practices, CLI commands, and instructions on how to fetch up-to-date information from Mastra's documentation.
-
-To install all available Mastra skills, run the following command:
-
-**npm**:
-
-```bash
-npx skills add mastra-ai/skills
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx skills add mastra-ai/skills
-```
-
-**Yarn**:
-
-```bash
-yarn dlx skills add mastra-ai/skills
-```
-
-**Bun**:
-
-```bash
-bun x skills add mastra-ai/skills
-```
-
-Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
-
-They're also available on [GitHub](https://github.com/mastra-ai/skills).
-
-### Update skill
-
-To update to the latest version of the Mastra skill, run:
-
-**npm**:
-
-```bash
-npx skills update mastra
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx skills update mastra
-```
-
-**Yarn**:
-
-```bash
-yarn dlx skills update mastra
-```
-
-**Bun**:
-
-```bash
-bun x skills update mastra
-```
-
-## Mastra CLI
-
-The [Mastra CLI](https://mastra.ai/reference/cli/mastra) gives your coding agent a direct line to your Mastra runtime.
-
-Agents can invoke other agents and run workflows. They can execute tools and inspect memory. They can also run evals or query traces and logs.
-
-**npm**:
-
-```bash
-npm install mastra@latest -g
-```
-
-**pnpm**:
-
-```bash
-pnpm add mastra@latest -g
-```
-
-**Yarn**:
-
-```bash
-yarn global add mastra@latest
-```
-
-**Bun**:
-
-```bash
-bun add mastra@latest --global
-```
-
-For example, your coding agent can run an agent, then pull traces to inspect the results:
-
-```bash
-mastra api --url http://localhost:4111 agent run weather-agent '{"messages":"What is the weather in London?"}'
-mastra api --url http://localhost:4111 trace list
-```
-
-Install the [Mastra skills](#mastra-skills) to teach your agent how to use the CLI. See the [CLI commands reference](https://mastra.ai/reference/cli/mastra) for the full list of available commands.
+For everyday AI-assisted development with Mastra skills and the CLI, see [Develop](https://mastra.ai/docs/getting-started/develop). This page covers other ways to give coding agents access to Mastra documentation.
 
 ## Embedded package docs
 
@@ -130,12 +27,10 @@ Examples for the [introduction page](https://mastra.ai/docs):
 - [`/docs/llms.txt`](https://mastra.ai/docs/llms.txt)
 - [`/docs.md`](https://mastra.ai/docs.md)
 
-## Mastra's documentation
-
-In addition to the [context files](#context-files) each documentation page also features a "Copy markdown" button at the top of the page. It'll copy the streamlined markdown version to your clipboard. Beside it, you'll find a dropdown menu to open the page on GitHub, in ChatGPT, Claude, and others.
-
 ## MCP docs server
 
+> **Warning:** The MCP docs server isn't recommended for everyday development. Use the [Mastra skill](https://mastra.ai/docs/getting-started/develop) instead because it's more up to date and performs better.
+
 The `@mastra/mcp-docs-server` package provides direct local access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
 
 These tools are designed to help agents retrieve precise, task-specific information, whether you're adding a feature to an agent or scaffolding a new project, or alternatively exploring how something works.
@@ -144,7 +39,7 @@ If you're unable to use a local MCP server and need to connect to a remote serve
 
 ### Installation
 
-The [`create-mastra`](https://mastra.ai/reference/cli/create-mastra) command installs Mastra skills automatically. It doesn't configure the MCP docs server. Add the server manually when you need MCP-specific tools such as the migration tool.
+The [`create-mastra`](https://mastra.ai/reference/cli/create-mastra) command doesn't configure the MCP docs server. Add the server manually when you need MCP-specific tools such as the migration tool.
 
 If there are no specific instructions for your tool below, you may be able to add the MCP server with this common JSON configuration.
 
@@ -354,7 +249,7 @@ Once configured, you can ask your AI tool questions about Mastra or instruct it
 - "How does working memory behave in Mastra and how can I use it to do `[task]`? It doesn't seem to work the way I expect."
 - "I saw there are new workflow features, explain them to me and then update `[workflow]` to use them."
 
-#### Troubleshooting
+### Troubleshooting
 
 1. **Server Not Starting**
 

package/.docs/reference/cli/create-mastra.md

@@ -201,6 +201,8 @@ Invalid input is rejected before templates are fetched or files are created.
 
 **--no-git** (`boolean`): Skip automatic Git initialization and the initial commit.
 
+**--no-install** (`boolean`): Skip dependency installation.
+
 **-t, --template \[template]** (`string`): Use a template slug or public GitHub URL. Omit the value to select interactively.
 
 **--timeout \<milliseconds>** (`number`): Positive integer timeout for dependency installation. Defaults to 60000.

package/.docs/reference/cli/mastra.md

@@ -103,7 +103,7 @@ These are forwarded to the Mastra model router and will work with any `"openai/.
 
 ## `mastra factory dev`
 
-Starts a development server for [Agent Builder](https://mastra.ai/docs/agent-builder/overview) development. It uses the same dev runtime and flags as [`mastra dev`](#mastra-dev) and writes to the same `.mastra/output` directory.
+Starts a development server for [Agent Builder](https://agent-builder.mastra.ai/) development. It uses the same dev runtime and flags as [`mastra dev`](#mastra-dev) and writes to the same `.mastra/output` directory.
 
 ```bash
 npx mastra factory dev
@@ -171,7 +171,7 @@ Comma-separated list of custom arguments to pass to the Node.js process, e.g. `-
 
 ## `mastra worker build`
 
-Bundles your Mastra application for worker deployment. Produces the same output as `mastra build` — a self-contained `.mastra/output/` directory.
+Bundles your Mastra application for worker deployment. Produces the same output as `mastra build`: a self-contained `.mastra/output/` directory.
 
 ```bash
 mastra worker build [options]
@@ -179,29 +179,45 @@ mastra worker build [options]
 
 ### Flags
 
-| Flag                  | Description                                                  |
-| --------------------- | ------------------------------------------------------------ |
-| `--dir <path>`        | Path to your Mastra source directory (default: `src/mastra`) |
-| `--root <path>`       | Project root directory (default: current directory)          |
-| `--tools <paths>`     | Comma-separated tool paths to include                        |
-| `--output-dir <path>` | Custom output directory (default: `.mastra/output`)          |
-| `--debug`             | Enable debug logging                                         |
+#### `--dir`
+
+Path to your Mastra source directory. Defaults to `src/mastra`.
+
+#### `--root`
+
+Project root directory. Defaults to the current directory.
+
+#### `--tools`
+
+Comma-separated tool paths to include in the bundle.
+
+#### `--output-dir`
+
+Custom output directory. Defaults to `.mastra/output`.
+
+#### `--debug`
+
+Enable debug logging during the build.
 
 ## `mastra worker start`
 
 > **Info:** You need to run `mastra worker build` or `mastra build` before using `mastra worker start`.
 
-Starts a worker process from a previously built bundle.
+Starts a worker process from a previously built bundle. The optional `name` argument sets `MASTRA_WORKERS` in the spawned process, controlling which worker starts.
 
 ```bash
 mastra worker start [name] [options]
 ```
 
-| Argument/Flag  | Description                                                         |
-| -------------- | ------------------------------------------------------------------- |
-| `name`         | Worker name to start. Sets `MASTRA_WORKERS` in the spawned process. |
-| `--dir <path>` | Path to the build output (default: `.mastra/output`)                |
-| `--env <path>` | Path to environment file (default: `.env.production`, then `.env`)  |
+### Flags
+
+#### `--dir`
+
+Path to the build output directory. Defaults to `.mastra/output`.
+
+#### `--env`
+
+Path to the environment file. Defaults to `.env.production`, falling back to `.env`.
 
 ### Examples
 
@@ -412,12 +428,16 @@ mastra env vars pull
 mastra env vars pull <env> --output .env.staging
 ```
 
-`<env>` can be an environment name, slug, or ID, and can be omitted when the project has exactly one environment. The file is written with `0600` permissions.
+`<env>` can be an environment name, slug, or ID, and can be omitted when the project has exactly one environment. The file is written with `0600` permissions. The command stops if the output file already exists. Pass `--force` to replace it.
 
 #### `-o, --output`
 
 File to write. Defaults to `.env`.
 
+#### `-f, --force`
+
+Replace an existing output file.
+
 ### `mastra env db`
 
 Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.

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

@@ -838,7 +838,7 @@ console.log(result.success) // true
 
 ## Version management
 
-Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See the [Editor overview](https://mastra.ai/docs/editor/overview) for an introduction to version management.
+Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See [Editor versioning](https://mastra.ai/docs/editor/overview) for lifecycle and selection behavior.
 
 ### Getting an agent with a specific version
 

package/.docs/reference/configuration.md

@@ -419,7 +419,7 @@ export const mastra = new Mastra({
 
 Text-to-speech providers for voice synthesis capabilities. Register voice providers to enable agents to convert text responses into spoken audio.
 
-Visit the [Voice documentation](https://mastra.ai/docs/voice/overview) to learn more.
+Visit the [Voice documentation](https://mastra.ai/guides/voice/overview) to learn more.
 
 > **Note:** Most users configure voice directly on agents. This top-level configuration is for defining reusable voice providers that can be shared across multiple agents.
 
@@ -440,7 +440,7 @@ export const mastra = new Mastra({
 
 Vector stores for semantic search and embeddings. Used in RAG pipelines, similarity search, and other embedding-based features. Mastra supports multiple vector databases including Pinecone, PostgreSQL with pgvector, MongoDB, and more.
 
-Visit the [RAG documentation](https://mastra.ai/docs/rag/overview) to learn more.
+Visit the [RAG documentation](https://mastra.ai/guides/rag/overview) to learn more.
 
 > **Note:** Most users create vector stores directly when building RAG pipelines. This top-level configuration is for defining reusable vector store instances that can be shared across your application.
 

package/.docs/reference/core/getEditor.md

@@ -33,5 +33,5 @@ This method doesn't accept any parameters.
 
 ## Related
 
-- [Editor overview](https://mastra.ai/docs/editor/overview)
+- [Editor](https://mastra.ai/docs/editor/overview)
 - [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor)

package/.docs/reference/core/getVector.md

@@ -20,5 +20,5 @@ mastra.getVector('testVectorStore')
 
 ## Related
 
-- [Vector stores overview](https://mastra.ai/docs/rag/vector-databases)
-- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [Vector stores overview](https://mastra.ai/guides/rag/vector-databases)
+- [RAG overview](https://mastra.ai/guides/rag/overview)

package/.docs/reference/core/listVectors.md

@@ -20,5 +20,5 @@ This method doesn't accept any parameters.
 
 ## Related
 
-- [Vector stores overview](https://mastra.ai/docs/rag/vector-databases)
-- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [Vector stores overview](https://mastra.ai/guides/rag/vector-databases)
+- [RAG overview](https://mastra.ai/guides/rag/overview)

package/.docs/reference/core/mastra-class.md

@@ -97,7 +97,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **notifications.dispatch.batchSize** (`number`): Maximum number of due notification records to process per dispatch run.
 
-**versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See Sub-agent versioning for details.
+**versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See Editor versioning for details.
 
 **versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors. Each selector can target a specific version by ID or by publication status.
 
@@ -135,7 +135,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 Re-drives every orphaned `running` durable-agent run across all registered durable agents. Called automatically on boot when `recovery.durableAgents` is `'auto'`. You can also call it directly for manual recovery or from a scheduled task.
 
-Requires persistent storage — with an in-memory store there is nothing to recover after a process restart.
+Requires persistent storage. With an in-memory store, there's nothing to recover after a process restart.
 
 ```typescript
 const result = await mastra.recoverAllDurableAgents()

package/.docs/reference/datasets/startExperiment.md

@@ -77,6 +77,14 @@ console.log(`Status: ${summary2.status}`)
 
 **maxRetries** (`number`): Maximum retries per item on failure. Defaults to 0 (no retries). Abort errors are never retried.
 
+**unmockedToolPolicy** (`'allow' | 'deny'`): Controls undeclared agent tool calls. allow executes them live. deny fails the item with TOOL\_MOCK\_NOT\_DECLARED before execution. An item-level value overrides this experiment default. (Default: `'allow'`)
+
+**persistence** (`ExperimentPersistencePolicy`): Controls whether this run writes experiment records and score records. Targets and scorers still execute, and results remain available in the returned summary.
+
+**persistence.experiments** (`'default' | 'none'`): Set to none to skip experiment creation, item results, progress, and terminal status writes.
+
+**persistence.scores** (`'default' | 'none'`): Set to none to skip score writes while still running scorers.
+
 ## Returns
 
 **result** (`Promise<ExperimentSummary>`): Summary of the completed experiment.

package/.docs/reference/datasets/startExperimentAsync.md

@@ -33,6 +33,10 @@ console.log(`Current status: ${experiment.status}`)
 
 Takes the same `StartExperimentConfig` as [`dataset.startExperiment()`](https://mastra.ai/reference/datasets/startExperiment).
 
+When `persistence.experiments` is set to `'none'`, `startExperimentAsync()` doesn't persist an experiment record, progress updates, or item results. Score persistence remains controlled separately by `persistence.scores`. Without an experiment event observer, the run is fire-and-forget, and the experiment API can't report whether it completed or failed.
+
+Use synchronous [`startExperiment()`](https://mastra.ai/reference/datasets/startExperiment) when the caller needs the returned summary. An experiment event observer can receive lifecycle events and the terminal summary.
+
 ## Returns
 
 **result** (`Promise<object>`): Immediate response with experiment ID.

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

@@ -54,7 +54,7 @@ export const myBrowserProvider: BrowserProvider<{ apiKey: string }> = {
 }
 ```
 
-Once registered, admins can pin the provider as a Builder default via [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults):
+Once registered, admins can pin the provider as a Builder default via [`BuilderAgentDefaults.browser`](https://agent-builder.mastra.ai/reference/builder-agent-defaults):
 
 ```typescript
 new MastraEditor({
@@ -72,6 +72,6 @@ new MastraEditor({
 
 ## Related
 
-- [Browser](https://mastra.ai/docs/agent-builder/browser): Concept and worked examples.
+- [Browser](https://agent-builder.mastra.ai/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

@@ -58,7 +58,7 @@ Once registered, admins can reference the provider from an inline workspace conf
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
+- [Workspace](https://agent-builder.mastra.ai/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

@@ -4,24 +4,17 @@
 
 The `MastraEditor` class sets up the editor system. Pass it to the `Mastra` constructor to turn on editor features like prompt blocks, agent code override, versioning, and tool providers.
 
-See the [Editor overview](https://mastra.ai/docs/editor/overview) for an introduction to what the editor does.
+See [Editor](https://mastra.ai/docs/editor/overview) for an introduction to what the editor does.
 
 ## Usage example
 
 ```typescript
 import { Mastra } from '@mastra/core'
 import { MastraEditor } from '@mastra/editor'
-import { ComposioToolProvider } from '@mastra/editor/providers/composio'
 
 export const mastra = new Mastra({
   agents: {/* your agents */},
-  editor: new MastraEditor({
-    toolProviders: {
-      composio: new ComposioToolProvider({
-        apiKey: process.env.COMPOSIO_API_KEY!,
-      }),
-    },
-  }),
+  editor: new MastraEditor(),
 })
 ```
 
@@ -43,7 +36,7 @@ export const mastra = new Mastra({
 
 **builder** (`AgentBuilderOptions`): Agent Builder configuration. See the AgentBuilderOptions reference. Omit or set enabled: false to disable the Builder.
 
-**source** (`'code' | 'db'`): Where agent overrides are stored. With 'db', overrides live in the configured storage backend and Studio shows the save and publish flow. With 'code', overrides live as per-agent JSON files on disk (routed through a local FilesystemStore) and Studio shows filesystem actions. See the Editor overview for the difference. (Default: `'db'`)
+**source** (`'code' | 'db'`): Where agent overrides are stored. With 'db', overrides live in the configured storage backend and Studio shows the save and publish flow. With 'code', overrides live as per-agent JSON files on disk (routed through a local FilesystemStore) and Studio shows filesystem actions. See Editor storage options for the difference. (Default: `'db'`)
 
 **codePath** (`string`): Directory used by the 'code' source for per-agent JSON files. Ignored when source is not 'code'. (Default: `'./mastra/editor/'`)
 
@@ -59,12 +52,12 @@ Each provider field above takes a record keyed by provider id. See the per-provi
 
 ## 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:
+The `builder` field enables the [Agent Builder](https://agent-builder.mastra.ai/), 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.
+- [Agent Builder overview](https://agent-builder.mastra.ai/): Concepts and getting started.
+- [AgentBuilderOptions](https://agent-builder.mastra.ai/reference/agent-builder-options): Full options schema.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Admin-pinned defaults for new agents.
+- [builder.configuration.agent.models](https://agent-builder.mastra.ai/reference/builder-models): Model allowlist and default model.
 
 ### Registering the Builder agent
 
@@ -85,7 +78,7 @@ export const mastra = new Mastra({
 
 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.
+See the [Agent Builder overview](https://agent-builder.mastra.ai/#prerequisites) for the full setup checklist.
 
 ## Namespaces
 
@@ -99,7 +92,7 @@ All namespaces extend a shared CRUD base class, so they expose the same `create`
 
 **agent.getById** (`(id: string, options?: GetByIdOptions) => Promise<Agent | null>`): Return a hydrated Agent instance for a stored agent. Pass options with versionId, versionNumber, or status ("draft" | "published" | "archived") to target a specific version. Default version requests are cached.
 
-**agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): Partially update a stored agent. Creates a new draft version with the provided snapshot fields (instructions, tools, memory, and so on) and invalidates the cache. Set memory to null to disable memory.
+**agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): Partially update a stored agent. Creates a version from the provided snapshot fields, assigns it to activeVersionId, and invalidates the cache. Set memory to null to disable memory.
 
 **agent.delete** (`(id: string) => Promise<void>`): Delete a stored agent and remove it from the Mastra runtime registry.
 
@@ -179,6 +172,24 @@ All namespaces extend a shared CRUD base class, so they expose the same `create`
 
 **scorer.clearCache** (`(id?: string) => void`): Clear the in-memory cache for one scorer or all scorers.
 
+### Agent namespace examples
+
+Create a stored override for an existing code-defined agent:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.create({
+  id: 'support-agent',
+  instructions: 'You are a friendly support agent for Acme.',
+  tools: {
+    search_kb: { description: 'Search the Acme knowledge base' },
+  },
+})
+```
+
 ## Methods
 
 ### Provider access
@@ -225,4 +236,6 @@ Returns the configured source (`'code'` or `'db'`), or `undefined` when the edit
 const source = mastra.getEditor()?.getSource()
 ```
 
-Returns: `'code' | 'db' | undefined`
+Returns: `'code' | 'db' | undefined`
+
+When `source` is omitted, Editor uses the configured database storage even though `getSource()` returns `undefined`. See [Editor storage options](https://mastra.ai/docs/editor/overview) for the storage workflows and [code-source versioning](https://mastra.ai/reference/editor/versioning) for activation and Git history behavior.

package/.docs/reference/editor/prompt-blocks.md

@@ -0,0 +1,137 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Prompt blocks
+
+Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text, embedded prompt blocks, and references to independently versioned prompt blocks.
+
+See [Prompt blocks](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+
+## Block types
+
+| Type               | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `text`             | Free-form text stored only in the agent version                   |
+| `prompt_block`     | A prompt block embedded in the agent version                      |
+| `prompt_block_ref` | A reference to an independently stored and versioned prompt block |
+
+Referenced blocks resolve at runtime. A missing or unpublished reference is omitted from the final instructions. Resolved nonempty blocks are joined with two newlines.
+
+The following example attaches a stored block and inline text to an agent:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.update({
+  id: 'support-agent',
+  instructions: [
+    { type: 'prompt_block_ref', id: 'brand-voice' },
+    { type: 'text', content: 'Answer only questions about Acme products.' },
+  ],
+})
+```
+
+## Template values
+
+Templates resolve values from the request context at runtime.
+
+| Syntax                    | Request context              | Output             |
+| ------------------------- | ---------------------------- | ------------------ |
+| `{{userName}}`            | `{ userName: 'Maya' }`       | `Maya`             |
+| `{{user.name}}`           | `{ user: { name: 'Maya' } }` | `Maya`             |
+| `{{task \|\| 'request'}}` | `{}`                         | `request`          |
+| `{{missingValue}}`        | `{}`                         | `{{missingValue}}` |
+
+Variable names must begin with a letter or underscore. Fallbacks must be single-quoted or double-quoted strings. Unresolved placeholders without a fallback remain unchanged. Objects and arrays are serialized as JSON. Other values are converted to strings.
+
+Pass values through [request context](https://mastra.ai/docs/server/request-context). Editor doesn't read a separate agent `variables` field.
+
+## Display conditions
+
+A prompt block can include a display condition that controls whether it's included in the final instructions. Each condition has three parts:
+
+- **Key**: The request-context field to check, such as `user.role` or `account.plan`.
+- **Operator**: The comparison to make, such as `equals`, `contains`, or `exists`.
+- **Value**: The value to compare against. The `exists` and `not_exists` operators don't need one.
+
+For example, the condition `user.role` `equals` `admin` includes the block only when request context contains `{ user: { role: 'admin' } }`.
+
+| Operator                                       | Example                                       | The block is included when                                |
+| ---------------------------------------------- | --------------------------------------------- | --------------------------------------------------------- |
+| `equals` / `not_equals`                        | `user.role` equals `admin`                    | The field strictly equals, or doesn't equal, the value    |
+| `contains` / `not_contains`                    | `user.tags` contains `beta`                   | A string contains the value or an array contains the item |
+| `greater_than` / `less_than`                   | `order.total` greater than `100`              | The numeric field is above or below the value             |
+| `greater_than_or_equal` / `less_than_or_equal` | `account.seats` greater than or equal to `10` | The numeric field is at or beyond the value               |
+| `in` / `not_in`                                | `user.region` in `['US', 'CA']`               | The field is, or isn't, in the supplied array             |
+| `exists` / `not_exists`                        | `account.plan` exists                         | The field has, or doesn't have, a non-null value          |
+
+Groups combine conditions with `AND` or `OR`. For example, this group includes a block for admins on a paid plan:
+
+```typescript
+const rules = {
+  operator: 'AND',
+  conditions: [
+    {
+      field: 'user.role',
+      operator: 'equals',
+      value: 'admin',
+    },
+    {
+      field: 'account.plan',
+      operator: 'in',
+      value: ['pro', 'enterprise'],
+    },
+  ],
+}
+```
+
+Dot paths are supported. An empty group evaluates to `true`, and an unknown operator evaluates to `false`. The storage type supports up to three nested group levels.
+
+Blocks without conditions are always included.
+
+## Programmatic API
+
+Access prompt blocks through `mastra.getEditor().prompt`. See the [`prompt` namespace](https://mastra.ai/reference/editor/mastra-editor) for complete method signatures.
+
+Create a prompt block:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.prompt.create({
+  id: 'brand-voice',
+  name: 'Brand voice',
+  description: 'Acme tone and style guidelines',
+  content: 'Write in a friendly, concise tone. Address the user as {{userName || "there"}}.',
+})
+```
+
+Update an existing block:
+
+```typescript
+await editor.prompt.update({
+  id: 'brand-voice',
+  content: 'Write in a friendly, concise tone. Greet the user by name when available.',
+})
+```
+
+`update()` creates a new draft when the content changes. Use `list()` to paginate through stored blocks, `getById()` to fetch one block, and `preview(blocks, context)` to resolve templates and conditions with draft references.
+
+## REST API
+
+The default Mastra server prefix is `/api`. A custom server prefix changes the paths below.
+
+| Method   | Path                                             | Description                  |
+| -------- | ------------------------------------------------ | ---------------------------- |
+| `GET`    | `/api/stored/prompt-blocks`                      | List stored prompt blocks    |
+| `POST`   | `/api/stored/prompt-blocks`                      | Create a stored prompt block |
+| `GET`    | `/api/stored/prompt-blocks/:storedPromptBlockId` | Get a stored prompt block    |
+| `PATCH`  | `/api/stored/prompt-blocks/:storedPromptBlockId` | Update a stored prompt block |
+| `DELETE` | `/api/stored/prompt-blocks/:storedPromptBlockId` | Delete a stored prompt block |
+
+## Version resolution
+
+Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/editor/overview) for the shared draft, publish, and restore lifecycle.

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

@@ -57,7 +57,7 @@ Once registered, admins can reference the provider from an inline workspace conf
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
+- [Workspace](https://agent-builder.mastra.ai/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.