@mastra/mcp-docs-server 1.2.7-alpha.3 → 1.2.7-alpha.6

package/.docs/models/providers/wandb.md

@@ -2,7 +2,7 @@
 
 # ![Weights & Biases logo](https://models.dev/logos/wandb.svg)Weights & Biases
 
-Access 18 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
+Access 25 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
 
 Learn more in the [Weights & Biases documentation](https://docs.wandb.ai).
 
@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "wandb/MiniMaxAI/MiniMax-M2.5"
+  model: "wandb/JetBrains/Mellum2-12B-A2.5B-Instruct"
 });
 
 // Generate a response
@@ -37,23 +37,30 @@ for await (const chunk of stream) {
 | Model                                                | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ---------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `wandb/deepseek-ai/DeepSeek-V3.1`                    | 161K    |       |           |       |       |       | $0.55      | $2          |
+| `wandb/deepseek-ai/DeepSeek-V4-Flash`                | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `wandb/deepseek-ai/DeepSeek-V4-Pro`                  | 1.0M    |       |           |       |       |       | $2         | $3          |
+| `wandb/google/gemma-4-31B-it`                        | 262K    |       |           |       |       |       | $0.12      | $0.35       |
+| `wandb/ibm-granite/granite-4.1-8b`                   | 131K    |       |           |       |       |       | $0.05      | $0.10       |
+| `wandb/JetBrains/Mellum2-12B-A2.5B-Instruct`         | 131K    |       |           |       |       |       | $0.05      | $0.10       |
 | `wandb/meta-llama/Llama-3.1-70B-Instruct`            | 128K    |       |           |       |       |       | $0.80      | $0.80       |
 | `wandb/meta-llama/Llama-3.1-8B-Instruct`             | 128K    |       |           |       |       |       | $0.22      | $0.22       |
 | `wandb/meta-llama/Llama-3.3-70B-Instruct`            | 128K    |       |           |       |       |       | $0.71      | $0.71       |
-| `wandb/meta-llama/Llama-4-Scout-17B-16E-Instruct`    | 64K     |       |           |       |       |       | $0.17      | $0.66       |
-| `wandb/microsoft/Phi-4-mini-instruct`                | 128K    |       |           |       |       |       | $0.08      | $0.35       |
 | `wandb/MiniMaxAI/MiniMax-M2.5`                       | 197K    |       |           |       |       |       | $0.30      | $1          |
-| `wandb/moonshotai/Kimi-K2.5`                         | 262K    |       |           |       |       |       | $0.50      | $3          |
+| `wandb/moonshotai/Kimi-K2.5`                         | 262K    |       |           |       |       |       | $0.60      | $3          |
+| `wandb/moonshotai/Kimi-K2.6`                         | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `wandb/moonshotai/Kimi-K2.7-Code`                    | 262K    |       |           |       |       |       | $0.94      | $4          |
 | `wandb/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-FP8` | 262K    |       |           |       |       |       | $0.20      | $0.80       |
-| `wandb/openai/gpt-oss-120b`                          | 131K    |       |           |       |       |       | $0.15      | $0.60       |
-| `wandb/openai/gpt-oss-20b`                           | 131K    |       |           |       |       |       | $0.05      | $0.20       |
+| `wandb/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B`     | 262K    |       |           |       |       |       | $0.75      | $3          |
+| `wandb/openai/gpt-oss-120b`                          | 131K    |       |           |       |       |       | $0.04      | $0.14       |
+| `wandb/openai/gpt-oss-20b`                           | 131K    |       |           |       |       |       | $0.03      | $0.13       |
 | `wandb/OpenPipe/Qwen3-14B-Instruct`                  | 33K     |       |           |       |       |       | $0.05      | $0.22       |
-| `wandb/Qwen/Qwen3-235B-A22B-Instruct-2507`           | 262K    |       |           |       |       |       | $0.10      | $0.10       |
-| `wandb/Qwen/Qwen3-235B-A22B-Thinking-2507`           | 262K    |       |           |       |       |       | $0.10      | $0.10       |
 | `wandb/Qwen/Qwen3-30B-A3B-Instruct-2507`             | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `wandb/Qwen/Qwen3-Coder-480B-A35B-Instruct`          | 262K    |       |           |       |       |       | $1         | $2          |
-| `wandb/zai-org/GLM-5-FP8`                            | 200K    |       |           |       |       |       | $1         | $3          |
-| `wandb/zai-org/GLM-5.1`                              | 200K    |       |           |       |       |       | $1         | $4          |
+| `wandb/Qwen/Qwen3.5-35B-A3B`                         | 262K    |       |           |       |       |       | $0.25      | $1          |
+| `wandb/Qwen/Qwen3.6-27B`                             | 262K    |       |           |       |       |       | $0.60      | $4          |
+| `wandb/Qwen/Qwen3.6-35B-A3B`                         | 262K    |       |           |       |       |       | $0.25      | $1          |
+| `wandb/zai-org/GLM-5.1`                              | 203K    |       |           |       |       |       | $1         | $4          |
+| `wandb/zai-org/GLM-5.2`                              | 262K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration
 
@@ -65,7 +72,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.inference.wandb.ai/v1",
-    id: "wandb/MiniMaxAI/MiniMax-M2.5",
+    id: "wandb/JetBrains/Mellum2-12B-A2.5B-Instruct",
     apiKey: process.env.WANDB_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -83,8 +90,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "wandb/zai-org/GLM-5.1"
-      : "wandb/MiniMaxAI/MiniMax-M2.5";
+      ? "wandb/zai-org/GLM-5.2"
+      : "wandb/JetBrains/Mellum2-12B-A2.5B-Instruct";
   }
 });
 ```

package/.docs/models/providers/xai.md

@@ -2,7 +2,7 @@
 
 # ![xAI logo](https://models.dev/logos/xai.svg)xAI
 
-Access 8 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
+Access 9 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
 
 Learn more in the [xAI documentation](https://docs.x.ai/docs/models).
 
@@ -38,6 +38,7 @@ for await (const chunk of stream) {
 | `xai/grok-4.20-0309-reasoning`     | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `xai/grok-4.20-multi-agent-0309`   | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `xai/grok-4.3`                     | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `xai/grok-4.5`                     | 500K    |       |           |       |       |       | $2         | $6          |
 | `xai/grok-build-0.1`               | 256K    |       |           |       |       |       | $1         | $2          |
 | `xai/grok-imagine-image`           | 8K      |       |           |       |       |       | —          | —           |
 | `xai/grok-imagine-image-quality`   | 8K      |       |           |       |       |       | —          | —           |

package/.docs/models/providers/zenifra.md

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![Zenifra logo](https://models.dev/logos/zenifra.svg)Zenifra
+
+Access 1 Zenifra model through Mastra's model router. Authentication is handled automatically using the `ZENIFRA_AI_KEY` environment variable.
+
+Learn more in the [Zenifra documentation](https://docs.zenifra.com).
+
+```bash
+ZENIFRA_AI_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "zenifra/alibaba/qwen3.6-35b-a3b"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Zenifra documentation](https://docs.zenifra.com) for details.
+
+## Models
+
+| Model                             | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| --------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `zenifra/alibaba/qwen3.6-35b-a3b` | 262K    |       |           |       |       |       | $0.19      | $0.48       |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://ai.zenifra.com/v1",
+    id: "zenifra/alibaba/qwen3.6-35b-a3b",
+    apiKey: process.env.ZENIFRA_AI_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "zenifra/alibaba/qwen3.6-35b-a3b"
+      : "zenifra/alibaba/qwen3.6-35b-a3b";
+  }
+});
+```

package/.docs/models/providers.md

@@ -136,6 +136,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Z.AI](https://mastra.ai/models/providers/zai)
 - [Z.AI Coding Plan](https://mastra.ai/models/providers/zai-coding-plan)
 - [Zeldoc](https://mastra.ai/models/providers/zeldoc)
+- [Zenifra](https://mastra.ai/models/providers/zenifra)
 - [ZenMux](https://mastra.ai/models/providers/zenmux)
 - [Zhipu AI](https://mastra.ai/models/providers/zhipuai)
 - [Zhipu AI Coding Plan](https://mastra.ai/models/providers/zhipuai-coding-plan)

package/.docs/reference/agents/channels.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.22.0`
 
-Channels connect agents to messaging platforms. Configure them via the `channels` property on the `Agent` constructor. The object you pass is a `ChannelConfig`. See the [Channels guide](https://mastra.ai/docs/agents/channels) for concepts and platform setup instructions.
+Channels connect agents to messaging platforms. Configure them via the `channels` property on the `Agent` constructor. The object you pass is a `ChannelConfig`. See the [Channels overview](https://mastra.ai/docs/capabilities/channels/overview) for concepts and platform setup instructions.
 
 ## Usage example
 
@@ -291,6 +291,6 @@ type InlineLinkEntry =
 
 ## Related
 
-- [Channels guide](https://mastra.ai/docs/agents/channels): Concepts, quickstart, and platform setup
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview): Concepts, quickstart, and platform setup
 - [Agent class](https://mastra.ai/reference/agents/agent): Constructor parameters and methods
 - [Chat SDK adapters](https://chat-sdk.dev/adapters): Adapter configuration and platform setup

package/.docs/reference/channels/channel-provider.md

@@ -64,4 +64,4 @@ const all = mastra.getChannelProviders()
 ## Related
 
 - [SlackProvider](https://mastra.ai/reference/channels/slack-provider)
-- [Channels](https://mastra.ai/docs/agents/channels)
+- [Channels](https://mastra.ai/docs/capabilities/channels/overview)

package/.docs/reference/channels/slack-provider.md

@@ -2,7 +2,7 @@
 
 # SlackProvider
 
-`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps via the Manifest API, runs the OAuth install flow, rotates configuration tokens, and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/docs/agents/channels) on the agent's `channels.adapters` instead.
+`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps via the Manifest API, runs the OAuth install flow, rotates configuration tokens, and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/docs/capabilities/channels/slack) on the agent's `channels.adapters` instead.
 
 ## Usage example
 
@@ -224,5 +224,5 @@ const result = await slack.connect('support-agent')
 ## Related
 
 - [ChannelProvider](https://mastra.ai/reference/channels/channel-provider): the interface `SlackProvider` implements
-- [Channels](https://mastra.ai/docs/agents/channels): concepts, platform setup, and the `createSlackAdapter` path
+- [Channels](https://mastra.ai/docs/capabilities/channels/overview): concepts, platform setup, and the `createSlackAdapter` path
 - [Channels reference](https://mastra.ai/reference/agents/channels): the `channels` config on the `Agent` constructor

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

@@ -736,6 +736,7 @@ Runs database migrations to update your storage schema. This command is useful w
 The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
 
 - **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
+- **ClickHouse legacy-to-vNext span migration**: Copies historical spans from the legacy `mastra_ai_spans` table to the vNext `mastra_span_events` schema. Runs in batches to stay within memory limits. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
 
 ```bash
 mastra migrate

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

@@ -0,0 +1,97 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# config.ts
+
+An agent's `config.ts` sets its model and runtime options. Use it for options that belong to the [`Agent`](https://mastra.ai/reference/agents/agent) itself, while sibling files provide instructions, tools, skills, et cetera.
+
+## What belongs in `config.ts`
+
+`config.ts` is the required entry point for a file-based agent's model and runtime options. Put agent-level settings here when they don't need their own file, such as the model, description, default execution options, retry behavior, scorers, and display identity.
+
+Keep adjacent concerns in sibling files when you want file-based routing to merge them into the agent. For example, use `instructions.md` for the always-on prompt and `tools/` for model-callable actions.
+
+## Quickstart
+
+The following `config.ts` plus an `instructions.md` file creates a working file-based agent:
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+Mastra uses the `weather` directory name as the default agent `id` and `name`. The sibling `instructions.md` supplies the required instructions.
+
+## Set the model
+
+The `model` field is the only required field in `agentConfig()`. The build fails when an agent directory doesn't provide a model. Other capabilities either come from sibling files or have defaults.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+## Identity from the directory
+
+A file-based agent's `id` and `name` default to the directory name. For `src/mastra/agents/weather/`, Mastra registers the agent as `weather` unless you override those fields.
+
+Override `id` or `name` when the stable routing key and the display name should differ.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  id: 'weather-assistant',
+  name: 'Weather Assistant',
+  model: 'openai/gpt-5.5',
+})
+```
+
+## Set runtime options
+
+`agentConfig()` accepts [`Agent` constructor options](https://mastra.ai/reference/agents/agent), except that `id`, `name`, and sibling-file fields can be supplied by the file-based convention. Use the Agent reference for the full option list.
+
+Please note:
+
+- File-based subagents require a non-empty `description` because the parent model uses it for delegation routing.
+- `defaultOptions`, `maxRetries`, `scorers`, and other Agent options can live in `config.ts` when they don't need their own file.
+
+## Where adjacent settings live
+
+Keep `config.ts` focused on runtime options. Use sibling files for concerns that benefit from their own location.
+
+| Setting      | File or folder                                                                  | Why it lives there                                                   |
+| ------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Instructions | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Keeps the always-on prompt readable as markdown                      |
+| Tools        | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Gives each callable action its own typed module                      |
+| Skills       | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Keeps load-on-demand procedures separate from always-on instructions |
+| Memory       | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)             | Configures persistent memory without crowding runtime options        |
+| Workspace    | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)       | Configures files and sandbox behavior separately from model settings |
+| Processors   | [`processors/`](https://mastra.ai/reference/file-based-agents/processors)       | Separates input and output processing pipelines                      |
+| Subagents    | [`subagents/`](https://mastra.ai/reference/file-based-agents/subagents)         | Gives each specialist child agent its own directory                  |
+
+## Precedence
+
+`config.ts` merges with the agent's other files according to these rules:
+
+| Domain       | Source A                      | Source B                                                                        | Winner                                                  |
+| ------------ | ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Instructions | Dynamic `config.instructions` | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Dynamic `config.instructions`                           |
+| Instructions | Static `config.instructions`  | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | `instructions.md`                                       |
+| Tools        | `config.tools`                | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Both merge; `config.tools` wins on key collisions       |
+| Tools        | Function `config.tools`       | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Function `config.tools`; discovered tools are ignored   |
+| Skills       | `config.skills`               | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Both merge; `config.skills` wins on name collisions     |
+| Skills       | Function `config.skills`      | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Function `config.skills`; discovered skills are ignored |
+| Memory       | `config.memory`               | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)             | `config.memory`                                         |
+| Workspace    | `config.workspace`            | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)       | `config.workspace`                                      |
+
+Missing both `instructions.md` and `config.instructions` fails the build. Missing both `config.memory` and `memory.ts` leaves the agent without memory.

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

@@ -0,0 +1,54 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Instructions
+
+An agent's `instructions.md` holds its always-on system prompt: the model reads it on every turn. Use it to define the agent's identity, tone, role, and standing rules.
+
+Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented out of `instructions.md` and into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
+
+## Quickstart
+
+Add an `instructions.md` at the agent root. Whatever you write becomes the prompt, so the shortest version is a single sentence.
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+## What goes in instructions
+
+Effective instructions cover the parts of an agent's behavior that don't change between requests:
+
+- Role and identity
+- Tone and style
+- Standing rules
+- Output format
+
+Move conditional, large, or action-oriented guidance into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
+
+## Dynamic instructions
+
+When the prompt needs to change per request, for example based on the current user or runtime context, set a dynamic `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  instructions: ({ runtimeContext }) => {
+    const tier = runtimeContext.get('tier') ?? 'standard'
+    return `You are a support agent. Treat this as a ${tier}-tier customer.`
+  },
+})
+```
+
+## Build-time behavior
+
+Mastra reads `instructions.md` and inlines its contents into the generated code when the bundler builds your project. The deployed agent doesn't read the file at runtime, so changes to `instructions.md` take effect only after the next build.
+
+## Precedence with config
+
+Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+
+- A dynamic (function) `instructions` in `config.ts` wins over `instructions.md`.
+- Otherwise `instructions.md` wins over a static `instructions` string.
+- If neither is present, the build fails and names the agent directory.

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

@@ -0,0 +1,58 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory
+
+A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
+
+Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.
+
+## Quickstart
+
+Create `memory.ts` next to the agent's `config.ts`:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage/overview) for more information.
+
+Use the same `resource` and `thread` values when calling the agent to continue a conversation:
+
+```typescript
+const response = await weatherAgent.generate('Remember that I prefer Celsius.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'weather-chat',
+  },
+})
+```
+
+## Configure memory
+
+Pass options to `new Memory()` when the default behavior isn't enough.
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory({
+  options: {
+    lastMessages: 20,
+    workingMemory: {
+      enabled: true,
+      scope: 'resource',
+    },
+  },
+})
+```
+
+Visit the [`Memory` reference](https://mastra.ai/reference/memory/memory-class) for constructor options. Use these pages for related memory features:
+
+- [Storage](https://mastra.ai/docs/storage/overview): configure persistence for memory data.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): retrieve relevant past messages by semantic meaning.
+- [Memory processors](https://mastra.ai/docs/memory/memory-processors): filter, trim, or transform messages before memory adds them to model context.
+
+## Precedence with config
+
+`config.memory` wins over `memory.ts`. If neither is present, the assembled file-based agent has no memory. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.

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

@@ -0,0 +1,32 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Observability
+
+Mastra configures [observability](https://mastra.ai/docs/observability/overview) from an `observability.ts` file directly under `src/mastra/`. The file default-exports an `Observability` instance that sets up tracing, logging, metrics, and feedback for the project.
+
+Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see [Observability overview](https://mastra.ai/docs/observability/overview) and [Observability configuration](https://mastra.ai/docs/observability/config).
+
+## Quickstart
+
+Create `src/mastra/observability.ts` and default-export an `Observability` instance:
+
+```typescript
+import { MastraStorageExporter, Observability } from '@mastra/observability'
+
+export default new Observability({
+  configs: {
+    default: {
+      serviceName: 'mastra',
+      exporters: [new MastraStorageExporter()],
+    },
+  },
+})
+```
+
+## Observability and storage
+
+`observability.ts` configures which signals are collected and where they're exported. [`storage.ts`](https://mastra.ai/reference/file-based-agents/storage) configures the project store that can persist observability records. For storage support by signal, see [Observability storage](https://mastra.ai/docs/observability/storage).
+
+## Precedence with code
+
+Code-registered observability wins over `observability.ts`. Use `observability.ts` when one project-wide configuration is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -0,0 +1,56 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Processors
+
+A file-based agent discovers [processors](https://mastra.ai/docs/agents/processors) from its `processors/` directory. Use this page for the file-based convention; use the processors guide for built-in processors, custom processors, streaming behavior, and advanced patterns.
+
+Files under `processors/input/` run before messages reach the model. Files under `processors/output/` run after the model responds. Each file default-exports one [`Processor`](https://mastra.ai/reference/processors/processor-interface), and the filename becomes its discovery key.
+
+## Quickstart
+
+Add an input processor by placing a processor file under `processors/input/`:
+
+```typescript
+import { PIIDetector } from '@mastra/core/processors'
+
+export default new PIIDetector({
+  strategy: 'block',
+})
+```
+
+This processor runs before user messages reach the model.
+
+## Add an output processor
+
+Output processors are good for filtering or transforming model responses before they're returned. This example redacts PII from the final response.
+
+```typescript
+import { PIIDetector } from '@mastra/core/processors'
+
+export default new PIIDetector({
+  strategy: 'redact',
+})
+```
+
+## Ordering
+
+Discovered processors are added after any processors defined in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). That means config processors run first.
+
+```text
+config.inputProcessors → processors/input/* → model
+model → config.outputProcessors → processors/output/* → response
+```
+
+If `config.inputProcessors` or `config.outputProcessors` is a function, discovered processors of that type are ignored with a warning because function-valued processors can't be statically merged.
+
+## Precedence with config
+
+Use `config.ts` for processors that need to be created dynamically or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.
+
+Precedence is:
+
+1. Function-valued `config.inputProcessors` or `config.outputProcessors`
+2. Array-valued `config.inputProcessors` or `config.outputProcessors`
+3. Discovered files under `processors/input/` or `processors/output/`
+
+Visit the [`Processor` reference](https://mastra.ai/reference/processors/processor-interface) for the full interface.

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.