@mastra/libsql 1.19.0-alpha.0 → 1.19.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @mastra/libsql
 
+## 1.19.0-alpha.2
+
+### Patch Changes
+
+- Dataset item scorer selections now persist across LibSQL writes and reads. Setting `scorerIds` to `null` clears an item override, while `[]` remains an explicit override with no scorers. ([#20191](https://github.com/mastra-ai/mastra/pull/20191))
+
+  ```typescript
+  await dataset.addItem({
+    input: 'Evaluate this response',
+    scorerIds: [],
+  });
+  ```
+
+- Updated dependencies [[`82201f7`](https://github.com/mastra-ai/mastra/commit/82201f75fae8e050a8de2df08b74875ee74c6b83), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`0a6598b`](https://github.com/mastra-ai/mastra/commit/0a6598bde80bde008986ad6616bed9632b9294cb), [`9e1dad8`](https://github.com/mastra-ai/mastra/commit/9e1dad8f7b1cab2bb7ade90e5b7561f24577b88a), [`2f43145`](https://github.com/mastra-ai/mastra/commit/2f4314504c03cbba280414ac81ba3197448ee6b0), [`34d34d8`](https://github.com/mastra-ai/mastra/commit/34d34d8c811df512fef4dd5459f79b7821be1866)]:
+  - @mastra/core@1.56.0-alpha.6
+
+## 1.19.0-alpha.1
+
+### Patch Changes
+
+- Stored workflow definitions now persist across restarts on every major database backend. ([#20471](https://github.com/mastra-ai/mastra/pull/20471))
+
+  Implement the `workflowDefinitions` storage domain for libsql, pg, mysql, mssql, mongodb, and spanner. Previously the stored-workflow persistence path (`POST /stored/workflows`, `Mastra.addStoredWorkflow`) only worked against `@mastra/core`'s in-memory store. Persistent adapters returned `undefined` from `storage.getStore('workflowDefinitions')` and threw when the HTTP handler tried to read/write a workflow.
+
+  ```ts
+  const workflowDefinitions = await storage.getStore('workflowDefinitions');
+  if (!workflowDefinitions) {
+    throw new Error('This storage adapter does not support the workflowDefinitions domain');
+  }
+
+  await workflowDefinitions.upsert({
+    id: 'greeting-workflow',
+    inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    outputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+    graph: [{ type: 'agent', id: 'greet', agentId: 'greeter-agent' }],
+  });
+
+  const { definitions, total } = await workflowDefinitions.list({ status: 'active' });
+  const definition = await workflowDefinitions.get('greeting-workflow');
+  await workflowDefinitions.delete('greeting-workflow');
+  ```
+
+  Each adapter now ships a `WorkflowDefinitions*` domain that:
+
+  - Creates the shared `mastra_workflow_definitions` table (or Mongo collection) from `WORKFLOW_DEFINITIONS_SCHEMA` during `init()`, plus a default index on `status`.
+  - Implements `upsert` / `get` / `list` / `delete` matching `WorkflowDefinitionsStorage` semantics (`list` supports `status` and `authorId` filters and orders by `updatedAt` desc). Partial upserts preserve unspecified fields, including `authorId` updates and `createdAt` / `updatedAt` semantics.
+  - Handles concurrent first-writes race-safely: if two callers upsert the same new id simultaneously, the losing insert detects the duplicate key, re-reads the row, and applies the partial-update path instead of failing.
+  - Round-trips the JSON columns (`inputSchema`, `outputSchema`, `stateSchema`, `requestContextSchema`, `metadata`, `graph`) through each adapter's JSON handling, so declarative workflow graphs rehydrate identically no matter which backend they were stored in. Malformed persisted JSON surfaces as an actionable error naming the row and column instead of hydrating raw strings.
+
+  Exported class names by adapter: `WorkflowDefinitionsLibSQL`, `WorkflowDefinitionsPG`, `WorkflowDefinitionsMySQL`, `WorkflowDefinitionsMSSQL`, `MongoDBWorkflowDefinitionsStore`, `WorkflowDefinitionsSpanner`. The composite stores (`LibSQLStore`, `PostgresStore`, `MySQLStore`, `MSSQLStore`, `MongoDBStore`, `SpannerStore`) auto-wire the new domain, so callers do not need to construct it manually — `storage.getStore('workflowDefinitions')` now returns a live handle.
+
+  The pg adapter reads `createdAt` / `updatedAt` from the auto-added `createdAtZ` / `updatedAtZ` `timestamptz` companion columns to avoid the naive-timestamp / local-TZ drift that a plain `TIMESTAMP` read exhibits under node-pg.
+
+  `@mastra/clickhouse` and `@mastra/cloudflare` register the new `mastra_workflow_definitions` table in their table/type maps so shared table constants stay exhaustive (no workflow-definitions domain implementation yet).
+
+- Updated dependencies [[`4844167`](https://github.com/mastra-ai/mastra/commit/4844167cff2d5ec5004e94edd34970833040fa3f), [`5faf93f`](https://github.com/mastra-ai/mastra/commit/5faf93f03e19daea394b9e2a923f2e4f833407f2), [`80ad891`](https://github.com/mastra-ai/mastra/commit/80ad891f8cd10379aa5b5af7510c763783b2ab56), [`a1cb98d`](https://github.com/mastra-ai/mastra/commit/a1cb98d11990b560b98482292a1f34aa1a2d9092), [`598ad82`](https://github.com/mastra-ai/mastra/commit/598ad82d41c41389a686338a1d0e50b7400e1938), [`1fd6aad`](https://github.com/mastra-ai/mastra/commit/1fd6aad1ea4a9d32f65efa832307c35e981a4c0a)]:
+  - @mastra/core@1.56.0-alpha.4
+
 ## 1.19.0-alpha.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.19.0-alpha.0"
+  version: "1.19.0-alpha.2"
 ---
 
 ## When to use
@@ -16,24 +16,23 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [Deploying](references/docs-agent-builder-deploying.md) - Swap local Agent Builder primitives for cloud-backed storage, filesystems, sandboxes, an EE license, auth, and a public channel URL for production.
-- [Agent Builder overview](references/docs-agent-builder-overview.md) - Let teammates create, configure, and operate Mastra agents from a browser, with admin-pinned defaults, RBAC, and channel integrations.
 - [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals and suspend tool execution, plus automatically resume suspended tools while keeping humans in control of agent workflows.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Workers](references/docs-deployment-workers.md) - Separate background processing from the API layer by running workflow execution, cron schedules, and background tasks in dedicated worker processes.
+- [Editor](references/docs-editor-overview.md) - Let collaborators update an agent in Studio, test their changes, and publish without editing code.
 - [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
 - [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
 - [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.
 - [Memory overview](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
 - [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
 - [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
-- [Retrieval, semantic search, reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
 - [Storage overview](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
 - [Snapshots](references/docs-workflows-snapshots.md) - Learn how to save and resume workflow execution state with snapshots in Mastra
 
 ### Guides
 
 - [AI SDK](references/guides-agent-frameworks-ai-sdk.md) - Use Mastra processors and memory with the Vercel AI SDK
+- [Retrieval, semantic search, reranking](references/guides-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
 
 ### Reference
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.19.0-alpha.0",
+  "version": "1.19.0-alpha.2",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agents-agent-approval.md

@@ -108,7 +108,7 @@ A tool's own `requireApproval` setting takes precedence over the function above.
 
 For sensitive tools, bind the approval to the exact tool name and arguments that were shown to the reviewer. If those arguments drift before execution, the tool shouldn't run under the old approval.
 
-The `tool-call-approval` chunk already includes `toolName`, `toolCallId`, and `args`. You can fingerprint those fields when the approval request is shown. The example below uses a simple JSON string as the fingerprint, but in production you should use a stable hash of the tool name and arguments:
+The `tool-call-approval` chunk already includes `toolName`, `toolCallId`, and `args`. You can fingerprint those fields when the approval request is shown. The example below uses a JSON string as the fingerprint, but in production you should use a stable hash of the tool name and arguments:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -174,7 +174,7 @@ async function approveReviewedToolCall(runId: string, toolCallId: string, finger
 await consumeApprovalStream(stream)
 ```
 
-In production, store the approved fingerprint in durable storage scoped to the user, run, tool call, and policy version. The `Set` above is intentionally small so the boundary is easy to see: the approval is consumed once, and only for the same canonical tool arguments that were reviewed.
+In production, store the approved fingerprint in durable storage scoped to the user, run, tool call, and policy version. The `Set` above is intentionally small so the boundary is clear: the approval is consumed once, and only for the same canonical tool arguments that were reviewed.
 
 ### Runtime suspension with `suspend()`
 

package/dist/docs/references/docs-deployment-workers.md

@@ -17,7 +17,7 @@ Workers matter when any of these apply:
 - Different parts of the system need to scale independently (e.g., more orchestration capacity without more API instances)
 - Background tool calls should run on dedicated compute
 
-If your application handles light traffic and workflows complete quickly, the default in-process setup works fine. Skip the worker infrastructure until you need it.
+If your application handles light traffic and workflows complete fast, the default in-process setup works fine. Skip the worker infrastructure until you need it.
 
 ## Worker types
 
@@ -33,11 +33,11 @@ The orchestration worker requires a PubSub backend that supports pull mode (e.g.
 
 ### Scheduler worker
 
-Polls storage for due cron schedules and publishes `workflow.start` events. It is a producer only, meaning it creates work for the orchestration worker to pick up.
+Polls storage for due cron schedules and publishes `workflow.start` events. It's a producer only, meaning it creates work for the orchestration worker to pick up.
 
 The scheduler reads declarative `schedule` fields from your workflow definitions automatically. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for how to declare schedules.
 
-**Do not run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
+**Don't run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
 
 ### Background task worker
 
@@ -47,7 +47,7 @@ The background task worker manages concurrency limits, task lifecycle, and resul
 
 ## How workers run
 
-### In-process (default)
+### In-process mode (default)
 
 With no configuration, Mastra creates and starts workers inside the API process. Events flow through an in-memory PubSub, and everything shares a single Node.js runtime.
 
@@ -64,7 +64,7 @@ This setup needs no external infrastructure beyond your storage adapter. It does
 
 ### Split processes
 
-To run workers separately, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
+To run workers in their own processes, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
 
 **Redis Streams + PostgreSQL**:
 
@@ -100,38 +100,38 @@ export const mastra = new Mastra({
 })
 ```
 
-Any [supported storage backend](https://mastra.ai/reference/workers/overview) works — swap the storage adapter for your preferred database.
+Any [supported storage backend](https://mastra.ai/reference/workers/overview) works. Swap the storage adapter for your preferred database.
 
 Run the same build artifact in multiple containers, each with a different [`MASTRA_WORKERS`](https://mastra.ai/reference/workers/overview) value to control which worker starts in each process.
 
 Split deployments require a distributed PubSub backend ([`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)), a shared [storage backend](https://mastra.ai/reference/workers/overview), and network connectivity between the orchestration worker and the API.
 
-The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with a Docker Compose example.
+The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with Docker Compose and Kubernetes examples.
 
 ## Network architecture
 
-Workers are internal infrastructure. They are not exposed to end users and do not need their own subdomain, public URL, or inbound HTTP route.
+Workers are internal infrastructure. They're not exposed to end users and don't need their own subdomain, public URL, or inbound HTTP route.
 
 In a split deployment:
 
-- **The API server is the only public-facing process.** It serves all client HTTP requests — REST endpoints, agent interactions, workflow triggers, and any custom routes.
-- **Workers connect outbound only.** They pull events from the distributed PubSub backend and read/write to the shared storage database. They do not accept inbound traffic from clients.
-- **The orchestration worker calls the API internally.** It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
+- **The API server is the only public-facing process**: It serves all client HTTP requests, including REST endpoints, agent interactions, workflow triggers, and any custom routes.
+- **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
+- **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
 All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. If a worker-related feature needs an HTTP route (for example, token minting for a voice integration), that route runs on the API server, not on the worker process.
 
 ## Known limitations
 
-- **No dead-letter queue**: Failed events are nacked and retried, but there is no DLQ for events that repeatedly fail.
+- **No dead-letter queue**: Failed events are nacked and retried, but there's no DLQ for events that fail after all retries.
 - **No built-in health endpoint**: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
 - **Scheduler is single-instance**: Running multiple scheduler processes causes duplicate schedule fires.
 - **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents) for details.
 
 ## Related
 
-- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose example and topology options
+- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose and Kubernetes examples
 - [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
-- [Workers reference](https://mastra.ai/reference/workers/overview): Environment variables, worker types, and storage backends
+- [Workers reference](https://mastra.ai/reference/workers/overview): Details about worker environment variables and types, with a list of supported storage backends
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): Declare cron schedules on workflows

package/dist/docs/references/docs-editor-overview.md

@@ -0,0 +1,349 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Editor
+
+Editor works like a CMS for Mastra agents. Collaborators can change an agent's instructions and tools in Studio without accessing the codebase or writing code. They can test changes before making them live.
+
+TypeScript defines the agent's default values. Editor saves changes separately instead of updating the source code, so collaborators can improve the agent while developers retain control over its model, identity, and runtime.
+
+A [deployed Studio](https://mastra.ai/docs/studio/deployment) makes Editor available to collaborators outside local development.
+
+> **📹 Watch:** Watch the [Mastra Editor workshop](https://www.youtube.com/watch?v=XTjuRoI7t_k\&pp=ygUWbWFzdHJhIGVkaXRvciB3b3Jrc2hvcA%3D%3D) for a guided walkthrough.
+
+## When to use Editor
+
+Use Editor when an agent is defined in code but the people responsible for its behavior shouldn't edit the codebase. It works well when instructions or tools change often and need testing before they reach users. If developers own every change and release agent configuration with the application, keep the [agent configuration in code](https://mastra.ai/docs/agents/overview) instead.
+
+## Quickstart
+
+Install `@mastra/editor`. This quickstart uses LibSQL to store Editor changes:
+
+**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
+```
+
+Add `MastraEditor` and storage to the `Mastra` instance. Existing storage can be reused instead of adding the LibSQL store shown here.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  agents: {/* existing agents */},
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+  editor: new MastraEditor(),
+})
+```
+
+## Use Editor in Studio
+
+In [Studio](https://mastra.ai/docs/studio/overview), open **Agents**, select an agent, then select **Editor**. Collaborators can update the agent's instructions and tools based on its Editor permissions.
+
+With database storage, save changes as a draft to test them without affecting the live agent. Publish the draft when it's ready to use.
+
+## Instructions
+
+The **Instructions** section shows the agent's system prompt defined in code. Collaborators can override it or add instruction blocks.
+
+An instruction block can include values from the current request. For example, `{{userName}}` inserts a name supplied through [request context](https://mastra.ai/docs/server/request-context). A [display condition](https://mastra.ai/reference/editor/prompt-blocks) can show a block only for a customer, role, or feature flag.
+
+### Prompt blocks
+
+A prompt block is a saved piece of instruction text that can be used by more than one agent. Create one under **Prompts**, publish it, then open an agent's **Instructions** section and select **Add block**.
+
+For example, agents for support, returns, and order status may all need the same refund policy. Save the policy as a prompt block and add it to each agent. When the policy changes, update and publish the block once instead of editing three agents.
+
+When a prompt block changes, every agent that references its published version receives the update. Draft changes are used only while previewing, so they don't affect the live agents until the block is published.
+
+See the [prompt blocks reference](https://mastra.ai/reference/editor/prompt-blocks) for template syntax, conditions, versions, and APIs.
+
+## Tools
+
+Tools let an agent take actions. Collaborators choose from the tools available to Editor, but they can't implement new tools in Studio. How tools become available depends on their source:
+
+- **Project tools** must be implemented and registered in the Mastra project by a developer.
+- **Integration tools** become available after a developer registers a provider such as Composio or Arcade. Collaborators can then browse the provider's catalog and add tools without each tool being added in code first.
+- **MCP tools** become available when an MCP client is configured. A collaborator with access can create the client in Studio, then choose from the tools exposed by its servers.
+
+In the agent's **Tools** section, collaborators can add the tools it needs or rewrite a tool's description for that agent. A more specific description helps the agent understand when to use the tool without changing the tool itself.
+
+### Project tools
+
+Developers can register a project tool on the `Mastra` instance to make it available in Editor:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+import { searchOrders } from './tools/search-orders'
+
+export const mastra = new Mastra({
+  tools: {
+    searchOrders,
+  },
+  agents: {/* agents */},
+  editor: new MastraEditor(),
+})
+```
+
+The Studio tool picker lists the tool. A collaborator can add it to an agent when that agent allows tool editing. The agent's Editor view also lists tools attached in code.
+
+### Composio
+
+[Composio](https://composio.dev) provides tools for services such as GitHub, Slack, and Gmail. Register the provider with a Composio API key to make its tool catalog available in Editor:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+import { ComposioToolProvider } from '@mastra/editor/composio'
+
+export const mastra = new Mastra({
+  agents: {/* agents */},
+  editor: new MastraEditor({
+    toolProviders: {
+      composio: new ComposioToolProvider({
+        apiKey: process.env.COMPOSIO_API_KEY!,
+      }),
+    },
+  }),
+})
+```
+
+Composio tool IDs look like `GITHUB_CREATE_ISSUE`. By default, a selected tool uses the connection associated with the agent's author. See [connection scope](https://agent-builder.mastra.ai/tool-providers#connection-scope) to use each caller's connection instead.
+
+### Arcade
+
+[Arcade](https://arcade.dev) provides another catalog of tools with built-in authentication. Register it with an Arcade API key:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+import { ArcadeToolProvider } from '@mastra/editor/arcade'
+
+export const mastra = new Mastra({
+  agents: {/* agents */},
+  editor: new MastraEditor({
+    toolProviders: {
+      arcade: new ArcadeToolProvider({
+        apiKey: process.env.ARCADE_API_KEY!,
+      }),
+    },
+  }),
+})
+```
+
+Arcade tool IDs use `Toolkit.ToolName` format, such as `Github.GetRepository`.
+
+### MCP clients
+
+Collaborators can also create a reusable MCP client in Studio and add its tools to an agent. Stored clients can start a local `stdio` server or connect to a remote HTTP server. Tool filters let each agent use only the tools it needs from that server.
+
+See the [Editor tools reference](https://mastra.ai/reference/editor/tools) for MCP configuration, conditions, filtering, and resolution order. See [`ToolProvider`](https://mastra.ai/reference/editor/tool-provider) for provider options.
+
+## Decide what collaborators can edit
+
+By default, collaborators can change an agent's instructions and manage its tools, including their descriptions. The agent's `id`, `name`, and `model` always come from code.
+
+Use the agent's `editor` field to limit what can be changed:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Help customers with Acme products.',
+  model: 'openai/gpt-5.6-sol',
+  editor: {
+    instructions: true,
+    tools: {
+      description: true,
+    },
+  },
+})
+```
+
+This agent lets collaborators change its instructions and improve the descriptions of tools already attached to it. They can't add or remove tools.
+
+| `editor` value                     | What collaborators can change               |
+| ---------------------------------- | ------------------------------------------- |
+| Omitted                            | Instructions, tools, and tool descriptions  |
+| `false`                            | Nothing                                     |
+| `{ instructions: true }`           | Instructions                                |
+| `{ tools: true }`                  | Tools and tool descriptions                 |
+| `{ tools: { description: true } }` | Descriptions of tools already added in code |
+
+Studio shows everything else as read-only. See [editor overrides](https://mastra.ai/reference/agents/agent) for the complete configuration.
+
+## Choose where changes are stored
+
+Editor can save changes in the configured database or as files in the repository.
+
+### Database storage
+
+The database option is the default. Editor uses the storage configured on the `Mastra` instance, so the application and Editor can share the same backend.
+
+To use a separate backend for Editor data, set the `editor` option on [`MastraCompositeStore`](https://mastra.ai/reference/storage/composite). Storage domains without an explicit route continue to use its `default` store.
+
+The following example keeps application and Editor data in separate LibSQL files:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MastraEditor } from '@mastra/editor'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  agents: {/* existing agents */},
+  storage: new MastraCompositeStore({
+    id: 'mastra-storage',
+    default: new LibSQLStore({
+      id: 'app-storage',
+      url: 'file:./mastra.db',
+    }),
+    editor: new LibSQLStore({
+      id: 'editor-storage',
+      url: 'file:./editor.db',
+    }),
+  }),
+  editor: new MastraEditor(),
+})
+```
+
+### Repository files
+
+Use the code source to keep overrides alongside application code. Developers can review the files in pull requests and deploy them with the application:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: {/* existing agents */},
+  editor: new MastraEditor({
+    source: 'code',
+    codePath: './mastra/editor',
+  }),
+})
+```
+
+In this mode, each edited agent has one JSON override file. Editor doesn't generate TypeScript or change the file where the agent was created. By default, an agent with the ID `support-agent` gets this file:
+
+```text
+mastra/editor/agents/support-agent.json
+```
+
+The file contains only the parts managed by Editor. For example:
+
+```json
+{
+  "instructions": "Help customers with Acme products and answer in their language.",
+  "tools": {
+    "searchOrders": {
+      "description": "Look up an order by its number"
+    }
+  }
+}
+```
+
+The agent's model, name, and other code-owned fields stay in its TypeScript file. Mastra reads the JSON and applies these values when the agent runs.
+
+When a collaborator saves in Studio, they can write the file to the local filesystem or download it. With a source-control integration, Studio can open a pull request instead. Git then provides the review and version history.
+
+See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for file locations and source options.
+
+## Versioning
+
+Database-backed agents and prompt blocks use draft and published versions. Saving creates a draft while the live agent continues using the published version. Publishing makes the draft live. Restoring an older version creates a draft that collaborators can test before publishing.
+
+Code-backed agent overrides use JSON files and Git history.
+
+### Select a version
+
+An application can choose a stored version for each request by passing a status (`published` or `draft`) or an exact version ID:
+
+```typescript
+const publishedAgent = await mastra.getAgentById('support-agent', {
+  status: 'published',
+})
+
+const draftAgent = await mastra.getAgentById('support-agent', {
+  status: 'draft',
+})
+
+const versionedAgent = await mastra.getAgentById('support-agent', {
+  versionId: 'abc-123',
+})
+```
+
+Version selection supports:
+
+- Compare two versions in an A/B test.
+- Give a draft to a small group before publishing it for everyone.
+- Keep production on the published version while staging uses the latest draft.
+- Pin a customer to a particular version.
+
+The same version controls work when a supervisor calls sub-agents. Developers can test a draft sub-agent without changing the rest of the system.
+
+See the [Editor versioning reference](https://mastra.ai/reference/editor/versioning) for version selection, sub-agent behavior, REST endpoints, and SDK methods.
+
+## Programmatic access
+
+Everything available in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor), the REST API, or the Client SDK. Use it to script bulk updates or seed stored configurations from code. It can also power automation that tunes agents based on [evaluation results](https://mastra.ai/docs/datasets/running-experiments).
+
+Call `mastra.getEditor()` when application code has access to the Mastra instance:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.update({
+  id: 'support-agent',
+  instructions: 'Help customers with Acme products. Reply in their language.',
+})
+```
+
+The direct `editor.agent.update()` method activates the new version immediately. To create a draft without changing the live agent, use the stored-agent REST API or Client SDK instead:
+
+```bash
+curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
+  -H "Content-Type: application/json" \
+  -d '{
+    "instructions": "Help customers with Acme products. Reply in their language."
+  }'
+```
+
+The default server prefix is `/api`. Developers can set a custom prefix in the server configuration.
+
+See the [`MastraEditor` namespaces](https://mastra.ai/reference/editor/mastra-editor) and [Client SDK agents API](https://mastra.ai/reference/client-js/agents) for available operations.
+
+## Next steps
+
+- [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor)
+- [Prompt blocks reference](https://mastra.ai/reference/editor/prompt-blocks)
+- [Editor tools reference](https://mastra.ai/reference/editor/tools)
+- [Editor versioning reference](https://mastra.ai/reference/editor/versioning)

package/dist/docs/references/docs-memory-overview.md

@@ -172,6 +172,20 @@ export const memoryAgent = new Agent({
 
 See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
 
+## What the model sees
+
+Each memory feature is added to either the system messages or the conversation messages in the request sent to the model. The layers depend on the features you've enabled. Working memory and semantic recall only appear when configured. The same applies to Observational Memory, while message history is on by default. The diagram shows where each enabled layer is placed in the request. The list below describes what each layer contributes:
+
+![Diagram showing how Mastra assembles the model context: system messages containing agent instructions, call-time system messages, working memory, cross-thread semantic recall, and Observational Memory, followed by conversation messages where message history and same-thread semantic recall interleave by timestamp, then call-time context messages, and finally the new user message](/img/memory/memory-context-window-light.svg)
+
+- [Working memory](https://mastra.ai/docs/memory/working-memory) is injected as a system message containing the template and the stored data. With `useStateSignals`, it's delivered as a state signal instead.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) matches from the current thread are inserted as regular messages and interleave with message history by timestamp. Matches from other threads are formatted into a system message instead.
+- [Message history](https://mastra.ai/docs/memory/message-history) adds the last N messages in chronological order. Your new message always comes last.
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) replaces old raw history: reflections and observations live in a system message, and only messages that haven't been observed yet remain in the conversation. A short continuation reminder is placed at the start of the conversation messages.
+- Context messages are the optional `context` array passed on a call, for example `agent.generate(msg, { context: [...] })`. Use them for one-off background such as app state or your own RAG results. They appear as regular conversation messages for that request only and are never saved to memory.
+
+Conversation messages are ordered by timestamp and deduplicated by message ID, so recalled older messages appear before recent history. Context messages passed at call time are stamped with the current time, which places them after history and recall but before your new message. To inspect the exact context for a real request, use [Tracing](https://mastra.ai/docs/observability/tracing/overview) and open the LLM call spans, see [Observability](#observability) below.
+
 ## Memory in multi-agent systems
 
 When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.

package/dist/docs/references/{docs-rag-retrieval.md → guides-rag-retrieval.md}

@@ -517,4 +517,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.

package/dist/docs/references/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/dist/docs/references/reference-storage-composite.md

@@ -188,6 +188,8 @@ export const mastra = new Mastra({
 
 **default** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in domains will use this storage's domains as fallbacks.
 
+**editor** (`MastraCompositeStore`): Storage adapter for Editor-owned domains, including agents, prompt blocks, scorers, MCP clients and servers, workspaces, and skills. Takes precedence over default storage but not explicit domain overrides.
+
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
 **domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.