@mastra/mcp-docs-server 1.2.7-alpha.4 → 1.2.7-alpha.8

package/.docs/reference/file-based-agents/server.md

@@ -0,0 +1,37 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Server
+
+Mastra configures its HTTP [server](https://mastra.ai/docs/server/mastra-server) from a `server.ts` file directly under `src/mastra/`. The server exposes agents, workflows, and other registered primitives as REST endpoints, and the file default-exports the same `ServerConfig` shape you'd pass to [`new Mastra()`](https://mastra.ai/reference/core/mastra-class).
+
+Use this page for the file-based convention. For server features, middleware, custom routes, generated API docs, and deployment behavior, see [Server overview](https://mastra.ai/docs/server/mastra-server).
+
+## Quickstart
+
+Create `src/mastra/server.ts` and default-export a `ServerConfig` object:
+
+```typescript
+import type { ServerConfig } from '@mastra/core/server'
+
+export default {
+  port: 4111,
+  host: '0.0.0.0',
+} satisfies ServerConfig
+```
+
+## Common configurations
+
+`server.ts` can configure the same server options as code registration:
+
+| Need                                  | Use                                       |
+| ------------------------------------- | ----------------------------------------- |
+| Bind to a deployment platform address | `host` and `port`                         |
+| Restrict browser access               | `cors`                                    |
+| Add webhooks or health checks         | `apiRoutes`                               |
+| Enable generated API docs             | `build.openAPIDocs` and `build.swaggerUI` |
+
+See [Mastra server](https://mastra.ai/docs/server/mastra-server), [middleware](https://mastra.ai/docs/server/middleware), and [custom API routes](https://mastra.ai/docs/server/custom-api-routes) for examples.
+
+## Precedence with code
+
+Code-registered server config wins over `server.ts`. Routes added during startup, such as channel webhooks, are preserved when file-based server config is applied.

package/.docs/reference/file-based-agents/skills.md

@@ -0,0 +1,56 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Skills
+
+A file-based agent discovers skills from its `skills/` directory and bundles them at build time. Skills are reusable procedures or reference material that the agent can load when relevant, instead of putting every detail into the always-on prompt.
+
+Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/agents/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/workspace/skills).
+
+## Quickstart
+
+The simplest skill is one markdown file under `skills/`. The filename becomes the skill name, and `description` tells the agent when to load it.
+
+```markdown
+---
+description: Use when reporting temperatures or comparing forecast units.
+---
+
+Always report temperatures in Celsius and Fahrenheit. Include the user's preferred unit first when known.
+```
+
+## Skills vs tools vs instructions
+
+| Need                                                 | Use                                                                             | Why                                                                  |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Always-on identity, tone, or rules                   | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The model should see the guidance every turn.                        |
+| Callable action with inputs and outputs              | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | The model needs to execute code, call APIs, or perform side effects. |
+| Detailed reference or procedure loaded when relevant | `skills/`                                                                       | The model only needs the full guidance for specific tasks.           |
+
+## Skill formats
+
+Mastra supports three file-based skill formats:
+
+| Format                        | Use it when                                                                                                      |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| TypeScript/JavaScript module  | You want to default-export a [`createSkill()`](https://mastra.ai/reference/agents/createSkill) result from code. |
+| Packaged `SKILL.md` directory | The skill has instructions plus supporting files under `references/`.                                            |
+| Flat markdown file            | The skill is one markdown file with frontmatter and instructions.                                                |
+
+For packaged skills, `description` is required in `SKILL.md` frontmatter. Flat markdown skills also require `description` in frontmatter. Write when to use the skill, not only what the skill contains.
+
+## What gets loaded
+
+File-based Agents skills are read at build time and added to the generated bundle. The deployed agent doesn't need to read those skill files from disk at runtime.
+
+For packaged skills, Mastra reads:
+
+- `SKILL.md` for metadata and instructions.
+- Files directly under `references/` as supporting reference content.
+
+Reference files are keyed by filename. Symlinked files and directories under `references/` are skipped during discovery.
+
+## Precedence with config
+
+Discovered skills merge with any `skills` in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a name collision, `config.skills` wins and a warning is logged.
+
+If `config.skills` is a function, discovered skills are ignored with a warning because function-valued skills can't be statically merged.

package/.docs/reference/file-based-agents/storage.md

@@ -0,0 +1,30 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage
+
+Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
+
+Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).
+
+## Quickstart
+
+Use [`LibSQLStore`](https://mastra.ai/reference/storage/libsql) for a local file-backed store:
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+
+export default new LibSQLStore({
+  id: 'mastra-storage',
+  url: 'file:./mastra.db',
+})
+```
+
+Mastra registers the store before file-based agents and workflows, so storage-dependent primitives bind to this store instead of the default in-memory store.
+
+## Production backends
+
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
+
+## Precedence with code
+
+Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/studio.md

@@ -0,0 +1,56 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Studio
+
+Mastra configures [Studio](https://mastra.ai/docs/studio/overview) from a `studio.ts` file directly under `src/mastra/`. The file default-exports a `StudioConfig` object for Studio authentication and authorization: who can access Studio, and what authenticated users can do.
+
+Use this page for the file-based convention. For auth providers, role-based access control (RBAC), and fine-grained authorization (FGA), see [Studio auth](https://mastra.ai/docs/studio/auth).
+
+## Quickstart
+
+For local development, you don't need `studio.ts`. Start the dev server and open Studio:
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Studio opens without authentication in local development. Add `studio.ts` when you're ready to secure a shared or production deployment.
+
+## Add authentication
+
+Use an auth provider to require sign-in before users can access Studio. This example uses [WorkOS](https://mastra.ai/docs/server/auth/workos):
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+import type { StudioConfig } from '@mastra/core/server'
+
+export default {
+  auth: new MastraAuthWorkos(),
+} satisfies StudioConfig
+```
+
+The auth provider handles who the user is. For what the user can do after sign-in, add RBAC or FGA in the same config. See [Studio auth](https://mastra.ai/docs/studio/auth) for full examples.
+
+## Precedence with code
+
+Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough; use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/subagents.md

@@ -0,0 +1,123 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Subagents
+
+A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.
+
+Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents).
+
+## Quickstart
+
+Declare one directory per subagent under `subagents/`:
+
+```text
+src/mastra/agents/
+└── supervisor/
+    ├── config.ts
+    ├── instructions.md
+    └── subagents/
+        └── researcher/
+            ├── config.ts
+            ├── instructions.md
+            └── tools/
+                └── search.ts
+```
+
+Mastra assembles `researcher` as its own agent and wires it into the supervisor's `agents` map. The parent model can delegate to it by using the generated `researcher` delegation tool.
+
+A subagent's `config.ts` must set a non-empty `description`. The parent model reads this when deciding whether to delegate.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  description: 'Researches a topic and returns cited findings.',
+})
+```
+
+## How the model delegates
+
+A subagent's `description` is routing text for the parent model. Write it like a [tool description](https://mastra.ai/reference/file-based-agents/tools): explain what the subagent does and when to delegate to it.
+
+The build fails when a discovered subagent doesn't provide a non-empty description.
+
+## Isolation
+
+Subagents are isolated. A subagent doesn't inherit its parent's tools, skills, workspace, memory, processors, or subagents. Each child is a self-contained agent with its own directory.
+
+If multiple agents should share the same dependency, define it in code and assign it through each agent's config.
+
+## Nesting
+
+Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory nested deeper is ignored with a warning.
+
+```text
+src/mastra/agents/
+└── supervisor/            # depth 0
+    └── subagents/
+        └── researcher/    # depth 1
+            └── subagents/
+                └── summarizer/ # depth 2
+```
+
+## Naming rules
+
+- A subagent id that collides with one of the parent's tool keys is a build error.
+- A duplicate subagent id under the same parent is a build error.
+- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
+- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
+
+## Example
+
+This supervisor coordinates a research-and-writing flow. The `researcher` subagent owns search tools, while the `writer` subagent owns a workspace for drafting files.
+
+```text
+src/mastra/agents/
+└── research-supervisor/
+    ├── config.ts
+    ├── instructions.md
+    └── subagents/
+        ├── researcher/
+        │   ├── config.ts
+        │   ├── instructions.md
+        │   └── tools/
+        │       └── search_web.ts
+        └── writer/
+            ├── config.ts
+            ├── instructions.md
+            └── workspace/
+                └── draft-template.md
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+```markdown
+You coordinate research and writing.
+
+Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5-mini',
+  description: 'Use to gather facts, sources, and concise research notes for a topic.',
+})
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  description: 'Use to turn research notes into a structured draft.',
+})
+```

package/.docs/reference/file-based-agents/tools.md

@@ -0,0 +1,63 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Tools
+
+A file-based agent discovers tools from `.ts` and `.js` files directly under its `tools/` directory. Each discovered file is imported at build time, the file must default-export a [`createTool()`](https://mastra.ai/reference/tools/create-tool) result, and the filename without its extension becomes the tool key the model can call.
+
+Use this page for the file-based convention. For tool schemas, execution options, output shaping, and approval options, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool).
+
+## Quickstart
+
+Place one tool per file under `tools/`. This file is exposed to the agent as `get_weather`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export default createTool({
+  id: 'get_weather',
+  description: 'Get the current weather for a city.',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    city: z.string(),
+    tempC: z.number(),
+  }),
+  execute: async ({ context }) => {
+    return { city: context.city, tempC: 21 }
+  },
+})
+```
+
+## Organizing tools
+
+Use one file per tool. Name the file after the action the model should take:
+
+- Use `get_weather.ts`, `search_docs.ts`, or `create_ticket.ts`.
+- Avoid vague names like `helper.ts`, `api.ts`, or `utils.ts`.
+- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`; discovery ignores those files.
+- Keep shared helper code outside `tools/` or in files that don't match the discovered extensions under `tools/`.
+
+Because nested directories aren't discovered as tools, group related tools with clear filename prefixes instead of subfolders, such as `calendar_create_event.ts` and `calendar_list_events.ts`.
+
+## Tool options
+
+The file-based convention only controls where the tool lives and how it's registered. The tool API still comes from `createTool()`:
+
+- Use `description` to tell the model when to call the tool.
+- Use `inputSchema` and `outputSchema` for structured inputs and outputs.
+- Use `toModelOutput` when the model should see a different shape than the raw value returned from `execute`.
+- Use `requireApproval` when a tool needs human confirmation before execution.
+
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
+
+## Runtime boundary
+
+Tool code runs in your app/server runtime when the agent calls the tool. If a tool needs filesystem or shell isolation, call [workspace](https://mastra.ai/reference/file-based-agents/workspace) or sandbox APIs explicitly.
+
+## Precedence with config
+
+Discovered tools merge with any `tools` in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a key collision, `config.tools` wins and a warning is logged.
+
+If `config.tools` is a function, discovered tools are ignored with a warning because function-valued tools can't be statically merged.

package/.docs/reference/file-based-agents/workflows.md

@@ -0,0 +1,52 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workflows
+
+Mastra discovers project-level workflows from `.ts` and `.js` files under `src/mastra/workflows/`. This convention isn't scoped to one agent: every file with a default export becomes a registered workflow, and the filename becomes the workflow key.
+
+Use this page for the file-based convention. For steps, schemas, control flow, streaming, state, and workflow execution, see [Workflows overview](https://mastra.ai/docs/workflows/overview).
+
+## Quickstart
+
+Create a file under `src/mastra/workflows/`, build the workflow with [`createWorkflow()`](https://mastra.ai/reference/workflows/workflow), and default-export it.
+
+```typescript
+import { createStep, createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const collectInputs = createStep({
+  id: 'collect-inputs',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ topic: z.string(), audience: z.string() }),
+  execute: async ({ inputData }) => ({
+    topic: inputData.topic,
+    audience: 'engineering',
+  }),
+})
+
+const writeSummary = createStep({
+  id: 'write-summary',
+  inputSchema: z.object({ topic: z.string(), audience: z.string() }),
+  outputSchema: z.object({ report: z.string() }),
+  execute: async ({ inputData }) => ({
+    report: `Daily report about ${inputData.topic} for ${inputData.audience}.`,
+  }),
+})
+
+const dailyReport = createWorkflow({
+  id: 'daily-report',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ report: z.string() }),
+})
+  .then(collectInputs)
+  .then(writeSummary)
+  .commit()
+
+export default dailyReport
+```
+
+Mastra registers this workflow under the `daily-report` key.
+
+## Precedence with code
+
+File-based workflows merge with workflows registered in [`new Mastra()`](https://mastra.ai/reference/core/mastra-class). On a key collision, the code-registered workflow wins.

package/.docs/reference/file-based-agents/workspace.md

@@ -0,0 +1,74 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspace
+
+A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they can read and write files and run shell commands without extra configuration.
+
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Workspaces](https://mastra.ai/docs/workspace/overview).
+
+## Default workspace
+
+Without `workspace.ts`, a file-based agent gets a default [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) when the build provides a per-agent workspace path. The default workspace uses:
+
+- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) rooted at the agent's bundled workspace directory.
+- [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) with the same working directory.
+
+This gives the agent file tools and shell tools automatically. The default workspace is per agent; subagents get nested workspace directories under their parent agent's workspace path.
+
+## Quickstart
+
+For the default workspace, don't add a file. Start with an agent directory like this:
+
+```text
+src/mastra/agents/weather/
+├── config.ts
+└── instructions.md
+```
+
+Add `workspace.ts` only when you need to customize the workspace:
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+export default new Workspace({
+  name: 'weather-workspace',
+  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
+  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
+})
+```
+
+Visit the [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class) for the full config.
+
+## When to customize the workspace
+
+Customize the workspace when the default local directory isn't enough. Common reasons include:
+
+- Point file tools at a different filesystem root.
+- Run shell commands in a different sandbox provider.
+- Add workspace search with BM25 or vector search.
+- Share one workspace across multiple agents.
+
+For provider patterns and runtime behavior, see the [workspace overview](https://mastra.ai/docs/workspace/overview), [sandbox guide](https://mastra.ai/docs/workspace/sandbox), and [workspace search](https://mastra.ai/docs/workspace/search).
+
+## Runtime boundary
+
+The workspace filesystem controls what file tools can read and write. The sandbox controls where shell commands run. Application runtime code, including code in [`tools/`](https://mastra.ai/reference/file-based-agents/tools), still runs in your app/server process unless it explicitly calls workspace or sandbox APIs.
+
+## Seed files
+
+Add a `workspace/` directory to ship starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
+
+```text
+src/mastra/agents/weather/
+├── config.ts
+└── workspace/
+    ├── README.md
+    └── data/
+        └── cities.json
+```
+
+The files are copied into the bundled workspace path, where workspace file tools and sandbox commands can read them. Symlinked seed files are skipped during mirroring.
+
+## Precedence with config
+
+`config.workspace` wins over `workspace.ts`; otherwise the default file-based workspace is used. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.

package/.docs/reference/index.md

@@ -175,6 +175,19 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.startExperimentAsync()](https://mastra.ai/reference/datasets/startExperimentAsync)
 - [.update()](https://mastra.ai/reference/datasets/update)
 - [.updateItem()](https://mastra.ai/reference/datasets/updateItem)
+- [config.ts](https://mastra.ai/reference/file-based-agents/config)
+- [Instructions](https://mastra.ai/reference/file-based-agents/instructions)
+- [Memory](https://mastra.ai/reference/file-based-agents/memory)
+- [Observability](https://mastra.ai/reference/file-based-agents/observability)
+- [Processors](https://mastra.ai/reference/file-based-agents/processors)
+- [Server](https://mastra.ai/reference/file-based-agents/server)
+- [Skills](https://mastra.ai/reference/file-based-agents/skills)
+- [Storage](https://mastra.ai/reference/file-based-agents/storage)
+- [Studio](https://mastra.ai/reference/file-based-agents/studio)
+- [Subagents](https://mastra.ai/reference/file-based-agents/subagents)
+- [Tools](https://mastra.ai/reference/file-based-agents/tools)
+- [Workflows](https://mastra.ai/reference/file-based-agents/workflows)
+- [Workspace](https://mastra.ai/reference/file-based-agents/workspace)
 - [API Reference](https://mastra.ai/reference/mastra-platform/api)
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)

package/.docs/reference/memory/memory-class.md

@@ -37,7 +37,7 @@ export const agent = new Agent({
 
 **options** (`MemoryConfig`): Memory configuration options.
 
-**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable loading conversation history into context. Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To prevent saving new messages, use the readOnly option instead.
+**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option.
 
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 

package/.docs/reference/memory/serialized-memory-config.md

@@ -38,7 +38,7 @@ new MastraEditor({
 
 **options.readOnly** (`boolean`): Treat memory as read-only — no new messages are stored.
 
-**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable.
+**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable message history entirely (messages are not loaded or saved).
 
 **options.semanticRecall** (`boolean | SemanticRecall`): Semantic recall configuration. See the Memory class reference for the full shape.
 

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [file-based agents](https://mastra.ai/docs/agents/file-based-agents) guide.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/file-based-agents) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files

package/.docs/reference/pubsub/lease-provider.md

@@ -130,4 +130,4 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread runs across processes
-- [Channels](https://mastra.ai/docs/agents/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Channels](https://mastra.ai/docs/capabilities/channels/overview): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/reference/storage/clickhouse.md

@@ -101,6 +101,38 @@ const observabilityStore = new ObservabilityStorageClickhouse({
 
 New projects should use `ObservabilityStorageClickhouseVNext` instead.
 
+### Migrating from legacy to vNext
+
+To migrate historical spans from the legacy `mastra_ai_spans` table to the vNext schema, run:
+
+**npm**:
+
+```bash
+npx mastra migrate
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra migrate
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra migrate
+```
+
+**Bun**:
+
+```bash
+bun x mastra migrate
+```
+
+The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping, deduplicates legacy rows, and preserves the original table as a backup. After migration, traces appear in Studio through the vNext adapter.
+
+> **Note:** The legacy table is not deleted. Drop it manually after verifying the migration.
+
 ### ClickHouse for every domain
 
 `ClickhouseStoreVNext` backs the `memory`, `workflows`, and `observability` domains with ClickHouse and uses the vNext observability adapter automatically. Use it when you want ClickHouse to back the entire application without wiring a composite store manually.

package/.docs/reference/storage/composite.md

@@ -156,6 +156,32 @@ export const mastra = new Mastra({
 })
 ```
 
+### Disabling a domain
+
+Set a domain to `false` to disable it. A disabled domain doesn't fall back to `default`, so data for that domain isn't persisted:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: {
+      // don't persist traces and spans
+      observability: false,
+    },
+  }),
+})
+```
+
 ## Options
 
 **id** (`string`): Unique identifier for this storage instance.
@@ -164,7 +190,7 @@ export const mastra = new Mastra({
 
 **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.
+**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.
 
 **domains.memory** (`MemoryStorage`): Storage for threads, messages, and resources.