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

package/.docs/reference/storage/retention.md

@@ -105,6 +105,8 @@ Deletes rows older than their configured `maxAge` across every domain that has a
 
 `prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks — each batch is its own transaction — so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
 
+Pass `options.retention` to replace the configured policies for that call only — for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
+
 Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy — never at `init()` — so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build; subsequent prunes reuse the index.
 
 ```typescript
@@ -116,6 +118,13 @@ const results = await storage.prune({
 for (const r of results) {
   console.log(`${r.domain}.${r.table}: deleted ${r.deleted}, done=${r.done}`)
 }
+
+// One-off pass with different policies (configured retention untouched):
+await storage.prune({
+  retention: {
+    observability: { spans: { maxAge: '1d' } },
+  },
+})
 ```
 
 Returns: `Promise<PruneResult[]>`
@@ -130,6 +139,8 @@ Returns: `Promise<PruneResult[]>`
 
 **signal** (`AbortSignal`): Cooperative cancellation. The batch loop checks it between batches and stops cleanly, returning partial results with done: false.
 
+**retention** (`RetentionConfig`): Replaces the store's configured retention policies for this call only — e.g. to skip a domain or prune more aggressively. The configured retention is unchanged.
+
 ##### PruneResult
 
 Each result describes one table's progress:

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.7-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`177010f`](https://github.com/mastra-ai/mastra/commit/177010ff096d2e4b28d89803be5b1a4cad2a0d6b), [`54a51e0`](https://github.com/mastra-ai/mastra/commit/54a51e0a484fe1ebad3fb1f7ef5282a075709eb7)]:
+  - @mastra/core@1.51.0-alpha.3
+
+## 1.2.7-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2)]:
+  - @mastra/core@1.51.0-alpha.2
+
 ## 1.2.7-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.7-alpha.4",
+  "version": "1.2.7-alpha.8",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.50.2-alpha.1",
+    "@mastra/core": "1.51.0-alpha.3",
     "@mastra/mcp": "^1.13.1"
   },
   "devDependencies": {
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.9",
-    "@internal/lint": "0.0.113",
     "@internal/types-builder": "0.0.88",
-    "@mastra/core": "1.50.2-alpha.1"
+    "@internal/lint": "0.0.113",
+    "@mastra/core": "1.51.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {

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

@@ -1,225 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Channels
-
-**Added in:** `@mastra/core@1.22.0`
-
-Channels connect your agents to messaging platforms like Slack, Discord, and Telegram. When a user sends a message on a platform, the agent receives it, processes it through the normal agent pipeline, and streams the response back to the conversation.
-
-## When to use channels
-
-Use channels when you want your agent to:
-
-- Respond to messages in Slack workspaces, Discord servers, or Telegram chats
-- Handle both direct messages and mentions in group conversations
-
-## Quickstart
-
-Configure channels directly on your agent using adapters from the [Chat SDK](https://chat-sdk.dev/adapters):
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { createSlackAdapter } from '@chat-adapter/slack'
-
-export const supportAgent = new Agent({
-  id: 'support-agent',
-  name: 'Support Agent',
-  instructions: 'You are a helpful support assistant.',
-  model: 'openai/gpt-5.5',
-  channels: {
-    adapters: {
-      slack: createSlackAdapter(),
-    },
-  },
-})
-```
-
-Register the agent in your Mastra instance with storage so channel state persists across restarts:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { LibSQLStore } from '@mastra/libsql'
-import { supportAgent } from './agents/support-agent'
-
-export const mastra = new Mastra({
-  agents: { supportAgent },
-  storage: new LibSQLStore({
-    url: process.env.DATABASE_URL,
-  }),
-})
-```
-
-Each adapter reads credentials from environment variables by default.
-
-## Platform setup
-
-Each platform requires credentials and event configuration. See the Chat SDK adapter docs for full setup: [Slack](https://chat-sdk.dev/adapters/slack), [Discord](https://chat-sdk.dev/adapters/discord), [Telegram](https://chat-sdk.dev/adapters/telegram).
-
-Mastra generates a webhook route for each platform at:
-
-```text
-/api/agents/{agentId}/channels/{platform}/webhook
-```
-
-For example: `/api/agents/support-agent/channels/slack/webhook`
-
-Point your platform's webhook or interactions URL to this path.
-
-### Local development
-
-Platform webhooks need a public URL to reach your local server. Use a tunnel to expose `localhost:4111`:
-
-```bash
-# ngrok
-ngrok http 4111
-
-# cloudflared
-npx cloudflared tunnel --url http://localhost:4111
-```
-
-Copy the generated URL and use it as the base for your webhook paths (e.g. `https://abc123.ngrok.io/api/agents/support-agent/channels/slack/webhook`).
-
-## Thread context
-
-When a user mentions the agent mid-conversation in a channel thread, the agent may not have prior context. By default, Mastra fetches the last 10 messages from the platform on the first mention.
-
-1. On the **first mention** in a thread, the agent fetches recent messages from the platform.
-2. These messages are prepended to the user's message as conversation context.
-3. After responding, the agent subscribes to the thread and has full history via Mastra's memory.
-4. Subsequent messages in that thread **don't** re-fetch from the platform.
-
-Set `threadContext: { maxMessages: 0 }` to disable this behavior. This only applies to non-DM threads.
-
-Mastra also adds a short system message telling the agent which channel and platform the request came from (DM vs public channel, platform name, bot display name). Set `threadContext: { addSystemMessage: false }` to skip it.
-
-## Tool approval
-
-Tools with `requireApproval: true` render as interactive cards with Approve and Deny buttons:
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-const deleteFile = createTool({
-  id: 'delete-file',
-  description: 'Delete a file from the system',
-  inputSchema: z.object({
-    path: z.string().describe('Path to the file to delete'),
-  }),
-  requireApproval: true,
-  execute: async ({ path }) => {
-    await fs.unlink(path)
-    return { deleted: path }
-  },
-})
-```
-
-When the agent calls this tool, users see a card with the tool name, arguments, and Approve/Deny buttons. The tool only executes after approval.
-
-Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode the agent uses `autoResumeSuspendedTools` to let the LLM decide based on the conversation context, since hidden mode doesn't post approval buttons.
-
-## Multi-user awareness
-
-In group conversations, Mastra automatically prefixes each message with the sender's name and platform ID so the agent can distinguish between speakers:
-
-```text
-[Alice (@U123ABC)]: Can you help me with this?
-[Bob (@U456DEF)]: I have a question too.
-```
-
-## Multimodal content
-
-Models like Gemini can natively process images, video, and audio. Combine `inlineMedia` and `inlineLinks` to let users share rich content with your agent across platforms:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { createDiscordAdapter } from '@chat-adapter/discord'
-import { google } from '@ai-sdk/google'
-
-export const visionAgent = new Agent({
-  id: 'vision-agent',
-  name: 'Vision Agent',
-  instructions: 'You can see images, watch videos, and listen to audio.',
-  model: google('gemini-3.1-flash-image-preview'),
-  channels: {
-    adapters: {
-      discord: createDiscordAdapter(),
-    },
-    inlineMedia: ['image/*', 'video/*', 'audio/*'],
-    inlineLinks: [
-      // Gemini treats YouTube URLs as native video file parts
-      { match: 'youtube.com', mimeType: 'video/*' },
-      { match: 'youtu.be', mimeType: 'video/*' },
-      'imgur.com', // HEAD-check imgur links; inline as file part if mimeType matches inlineMedia
-    ],
-  },
-})
-```
-
-With this configuration:
-
-- A user uploads a screenshot and the agent describes what it sees
-- A user uploads an `.mp4` clip and the agent summarizes the video
-- A user pastes a YouTube link and the agent watches and discusses the video
-- A user pastes an imgur link and the agent sees the image directly
-
-By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupported types are described as text summaries so the agent knows about the file without crashing models that reject them.
-
-> **Note:** See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced mime types.
-
-## Serverless deployment
-
-On serverless platforms like Vercel, each request runs in a separate, short-lived instance. Channels need two things to work reliably in that environment: a way to keep the function alive while the agent responds, and a shared pub/sub so instances can coordinate.
-
-### Keep the function alive with `waitUntil`
-
-A channel webhook returns a `200` response right away, then the agent runs in the background to post its reply. On most serverless platforms the function is frozen as soon as it responds, which kills the run before the agent answers. Pass a `waitUntil` function so the platform keeps the instance alive until the run finishes.
-
-On Vercel, pass `waitUntil` from `@vercel/functions`:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { createSlackAdapter } from '@chat-adapter/slack'
-import { waitUntil } from '@vercel/functions'
-
-export const agent = new Agent({
-  id: 'agent',
-  channels: {
-    adapters: {
-      slack: createSlackAdapter(),
-    },
-    waitUntil,
-  },
-})
-```
-
-Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soon as the response is sent. Cloudflare Workers and Netlify Functions are detected automatically from the request context, so they don't need it. For runtimes where `waitUntil` lives on the request context but isn't detected automatically, use `resolveWaitUntil`. See the [Channels reference](https://mastra.ai/reference/agents/channels) for details.
-
-### Coordinate instances with a shared pub/sub
-
-Channels route messages through the agent's signal pipeline, and each run acquires a lease on its thread so a single run owns the conversation at a time. The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can land on a different instance than the one running the agent. Without a shared pub/sub, that instance can't reach the active run and starts its own, leaving the original run untouched and the thread processed twice.
-
-Configure a shared pub/sub backed by Redis Streams on the `Mastra` instance so leases and signals coordinate across instances:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { RedisStreamsPubSub } from '@mastra/redis-streams'
-
-export const mastra = new Mastra({
-  agents: { agent },
-  pubsub: new RedisStreamsPubSub({
-    url: process.env.REDIS_URL,
-    keyPrefix: 'mastra:my-app',
-  }),
-})
-```
-
-Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
-
-## Related
-
-- [Guide: Building a Slack assistant](https://mastra.ai/guides/guide/slack-assistant)
-- [Agent overview](https://mastra.ai/docs/agents/overview)
-- [Tool approval](https://mastra.ai/docs/agents/agent-approval)
-- [Channels reference](https://mastra.ai/reference/agents/channels)
-- [Chat SDK adapters](https://chat-sdk.dev/adapters)

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

@@ -1,297 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# File-based agents
-
-**Added in:** `@mastra/core@1.48.0`
-
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
-
-You can define an agent by file convention instead of constructing it in code. Mastra discovers a directory under `src/mastra/agents/<name>/`, assembles an [`Agent`](https://mastra.ai/reference/agents/agent), and registers it on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
-
-## When to use file-based agents
-
-Use file-based agents when you want one directory per agent, with configuration, instructions, tools, skills, workspace files, and subagents grouped together.
-
-Keep using [`new Agent()`](https://mastra.ai/reference/agents/agent) in code when you need dynamic configuration, programmatic registration, or a shared agent instance across modules. Both approaches can coexist: code-registered agents are always present, and the bundler adds file-based agents when you run through the Mastra CLI.
-
-## Quickstart
-
-Create a directory for the agent and add a `config.ts`. Use `agentConfig` so the partial config is typed while sibling files supply the rest.
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  // instructions omitted -> taken from instructions.md
-  // tools omitted -> taken from tools/*.ts
-})
-```
-
-Add the agent instructions:
-
-```markdown
-You are a helpful weather assistant. Answer questions about current conditions and forecasts.
-```
-
-Add a tool. The filename becomes the tool key, so this file is exposed 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() }),
-  execute: async ({ context }) => ({ city: context.city, tempC: 21 }),
-})
-```
-
-Your `src/mastra/index.ts` stays the same. The discovered agent is registered automatically when you run the app through `mastra dev` or `mastra build`.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { Agent } from '@mastra/core/agent'
-
-const supportAgent = new Agent({
-  id: 'support',
-  name: 'support',
-  instructions: 'You are a support agent.',
-  model: 'openai/gpt-5.5',
-})
-
-// `support` is registered in code; `weather` is discovered from the filesystem.
-export const mastra = new Mastra({
-  agents: { support: supportAgent },
-})
-```
-
-Start the app through the Mastra CLI:
-
-**npm**:
-
-```bash
-npx mastra dev
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx mastra dev
-```
-
-**Yarn**:
-
-```bash
-yarn dlx mastra dev
-```
-
-**Bun**:
-
-```bash
-bun x mastra dev
-```
-
-## Folder structure
-
-The following table shows the supported file-based agent surface:
-
-| File / directory                        | Maps to                                                                                                                                   |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `agents/<name>/config.ts`               | Default export merged into the agent config. `id` and `name` default to `<name>`.                                                         |
-| `agents/<name>/instructions.md`         | The agent `instructions`. The file contents are inlined into generated code.                                                              |
-| `agents/<name>/tools/*.ts`              | Each default-exported [`createTool()`](https://mastra.ai/reference/tools/create-tool). The tool key defaults to the filename.             |
-| `agents/<name>/skills/*.ts`             | Each default-exported [`createSkill()`](https://mastra.ai/reference/agents/createSkill), added to the agent `skills`.                     |
-| `agents/<name>/skills/<skill>/SKILL.md` | A packaged skill. Frontmatter supplies `name` and `description`, the body is the instructions, and files under `references/` are inlined. |
-| `agents/<name>/skills/<skill>.md`       | A flat skill. The filename is the skill name and the body is the instructions.                                                            |
-| `agents/<name>/memory.ts`               | Default export: a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance used as the agent `memory`.                        |
-| `agents/<name>/workspace.ts`            | Default export: a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) for the agent.                                     |
-| `agents/<name>/workspace/`              | Seed files mirrored into the agent's default workspace at build time.                                                                     |
-| `agents/<name>/subagents/<childId>/`    | A declared subagent with the same layout as an agent directory. Wired into the parent as a delegation tool named `<childId>`.             |
-
-Test files named `*.test.ts`, `*.spec.ts`, `*.test.js`, and `*.spec.js` are ignored during tool and skill discovery.
-
-## Add skills
-
-Add skills to a file-based agent by placing them under `agents/<name>/skills/`. Three layouts are supported, and they're inlined into the bundle at build time so the deployed agent doesn't read them from disk at runtime.
-
-- A `.ts` file can default-export `createSkill()`:
-
-  ```typescript
-  import { createSkill } from '@mastra/core/skills'
-
-  export default createSkill({
-    name: 'forecasting',
-    description: 'Use when the user asks about multi-day forecasts.',
-    instructions: 'Summarize the forecast day by day and call out precipitation.',
-  })
-  ```
-
-  > **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
-
-- A packaged `SKILL.md` directory uses frontmatter for the name and description. Files under `references/` are inlined with the skill.
-
-  ```markdown
-  ---
-  name: severe-weather
-  description: Use when conditions include storms, flooding, or other hazards.
-  ---
-
-  Lead with the active alert, then give safety guidance.
-  ```
-
-- A flat `<skill>.md` file uses the filename as the skill name:
-
-  ```markdown
-  Always report temperatures in both Celsius and Fahrenheit.
-  ```
-
-Discovered skills merge with any `skills` in `config.ts`. 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 they can't be statically merged.
-
-## Add memory
-
-Give a file-based agent [memory](https://mastra.ai/docs/memory/overview) by adding a `memory.ts` that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance:
-
-```typescript
-import { Memory } from '@mastra/memory'
-
-export default new Memory()
-```
-
-The exported instance becomes the agent's `memory`. You can also set `memory` directly in `config.ts`. `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is present, the agent has no memory, which is the default.
-
-## Add a workspace
-
-When a file-based agent is discovered through `mastra dev` or `mastra build`, it gets a default workspace unless `config.workspace` or `workspace.ts` supplies one. The default workspace uses a contained filesystem and shell sandbox rooted at a per-agent `workspace/` directory in the bundle.
-
-To customize it, add a `workspace.ts` that default-exports a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class):
-
-```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' }),
-})
-```
-
-You can also set `workspace` directly in `config.ts`. `config.workspace` wins over `workspace.ts`, and `workspace.ts` wins over the default workspace.
-
-### Seed files
-
-Add a `workspace/` directory to ship files with the agent. Mastra mirrors every file under it into the agent's default 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
-```
-
-Seed files are copied into the bundle next to the running server. Commit the starting files alongside the agent that uses them.
-
-## Add subagents
-
-A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `workspace/`.
-
-```text
-src/mastra/agents/
-  supervisor/
-    config.ts
-    instructions.md
-    subagents/
-      researcher/
-        config.ts
-        instructions.md
-        tools/
-          search.ts
-```
-
-Each subagent is assembled as its own agent and wired into the parent's `agents` map. The agent loop lowers it into a model-visible delegation tool. The tool name is the bare directory name, so the example above exposes `researcher` to the supervisor.
-
-A subagent's `config.ts` must set a non-empty `description`. The description is what the model sees when deciding whether to delegate, so the build fails if it's missing.
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  description: 'Researches a topic and returns cited findings.',
-})
-```
-
-Subagents are isolated. A subagent inherits nothing from its parent. Its tools, skills, and workspace come only from its own directory, and any absent slot falls back to the same framework defaults as a top-level agent.
-
-Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory deeper than that's 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.
-
-## Precedence rules
-
-File-based and code-based agents coexist with deterministic rules:
-
-- **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
-- **A folder can hold a code agent:** If `config.ts` exports a configured `new Agent({ id: 'file-based-agent', ... })`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
-- **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
-- **Model:** A missing `model` fails the build and names the agent directory.
-- **Tools:** Tools from `tools/*.ts` merge with `config.tools`. 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.
-- **Skills:** Skills from `skills/` merge with `config.skills`. 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.
-- **Memory:** `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is set, the agent has no memory.
-- **Workspace:** `config.workspace` wins over `workspace.ts`, which wins over the default workspace.
-- **Subagents:** Subagents from `subagents/` merge with `config.agents`. On an id collision, `config.agents` wins and a warning is logged. A subagent id that collides with a tool key, or a duplicate subagent id, is a build error.
-
-## What happens at build time
-
-File-based agents are discovered by the Mastra **bundler**, the step that runs under `mastra dev` and `mastra build`.
-
-File-based agents are registered only when your app runs through the Mastra CLI. If you import your `mastra` instance directly, `agents/<name>/` directories aren't discovered.
-
-When you consume Mastra as a library, register those agents in code instead of relying on file discovery:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { Agent } from '@mastra/core/agent'
-
-const weather = new Agent({
-  id: 'weather',
-  name: 'weather',
-  instructions: 'You are a helpful weather assistant.',
-  model: 'openai/gpt-5.5',
-})
-
-export const mastra = new Mastra({
-  agents: { weather },
-})
-```
-
-## Related
-
-- [Agents overview](https://mastra.ai/docs/agents/overview)
-- [Tools](https://mastra.ai/docs/agents/using-tools)
-- [Skills](https://mastra.ai/docs/agents/skills)
-- [Memory](https://mastra.ai/docs/memory/overview)
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
-- [Workspace](https://mastra.ai/docs/workspace/overview)
-- [Studio overview](https://mastra.ai/docs/studio/overview)
-- [`Agent` reference](https://mastra.ai/reference/agents/agent)
-- [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)
-- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
-- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
-- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)